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

4 インストール

 SYCL版PARCELの導入方法について説明する.
 PARCEL はヘッダーファイルのみで構成されている. ./Include/parcel_sycl.hpp をインクルードし, SYCL対応コンパイラでコンパイルすれば利用可能である. ライブラリとしての事前ビルドやインストール作業は不要である.

 ただし次の 3 点に注意する.

 SYCL対応コンパイラの導入は前章を参照のこと. spack で PARCEL ごと入れる方法は「spack によるインストール」に, Python のパッケージは「Python のパッケージ」に示す.

4.1 パッケージの構成

 配布パッケージ (PARCEL_SYCL v1.2) の構成を示す. ライブラリ本体は Include/ のヘッダだけであり, 他はサンプルと試験である.

場所 内容
Include/ ライブラリ本体 (ヘッダのみ). parcel_sycl.hpp をインクルードする
capi/ C言語・Fortran の API. parcel_sycl_c.h (C の宣言), parcel_sycl_mod.f90 (Fortran のモジュール), wrapper_parcel_sycl.cpp (実装. SYCL 対応コンパイラでビルドする), parcel_capi_default.hpp (ラッパのコンパイル時の既定値: 内部精度と旧 API の設定)
examples/ quick_start.cpp・quick_start_c.c・quick_start_f.f90・quick_start.py (クイックスタートの C++・C言語・Fortran・Python の例), example_pcg_ks.cpp (pcg と ks_arnoldi), sample_c.c・sample_f.f90 (C言語・Fortran の API で全ソルバを呼んで検証する例), sample_f_mpi_stub.f90 (MPI なしのビルドで sample_f.f90・quick_start_f.f90 を組むための 1 プロセス用 mpi モジュール), problem.f90 (旧 API 用の行列生成), build_examples.sh (以上をまとめてビルドするスクリプト. コンパイラ・ターゲット・LAPACK は環境変数で変える), run_quick_checks.sh (ビルド後の確認. 「ビルド後の確認」)
python/ Python のパッケージ parcel (インストールの「Python のパッケージ」, 使用方法の Python). parcel/ (Python の層), src/ (ネイティブ層 libparcel_py.so のソース), envs/mac_brew.sh (macOS + Homebrew でビルドするときの設定), pyproject.toml・CMakeLists.txt (pip でのビルドの設定)
spack/ spack のレシピ parcel-sycl・py-parcel-sycl (spack_repo/parcel/) と, spack の取得から PARCEL までをゼロから入れるスクリプト (stack/install_stack.sh, 確認用の stack/check_stack.sh, 環境ごとの定義 stack/envs/<環境>/) (「spack によるインストール」)
tests/verify/ 検証用サンプル parcel_krylov_sample_verify.cpp とその既定値 parcel_default.hpp, メモリ使用量の表示 (diag_mem.hpp. PARCEL_MEM_REPORT), 試験用の行列の生成 (Poisson・移流拡散・非構造)
tests/regression/ 回帰試験のジョブスクリプトの生成器 (gen_regression.py), 投入と集計のスクリプト, double-double の検査 (ddcheck), Python の API の試験 (sample_py.py), スケジューラの無い計算機で回帰試験を流すスクリプト (run_local.sh)
tests/perf/ 性能試験のジョブスクリプトの生成器 (gen_perf.py, 混合精度のgen_perf_prec.py) と集計のスクリプト
tests/site_config.py 試験の環境ごとの設定 (キュー, モジュール, コンパイルフラグ, 課金先). 自分の環境に合わせて書き換える
tests/check_version.py 版の照合 (ビルド不要). 版を書き写しているファイル (Python のパッケージ, spack のレシピと環境の定義の parcel-sycl@, CITATION.cff) が Include/parcel_version.hpp と同じかを調べる (「版の確かめ方」)
tools/make_tarball.py 配布 tarball と sha256 を作るスクリプト (「配布物の確認」)
README.md, CHANGELOG.md 概要と v1.2 の変更点
CITATION.cff, SUPPORT.md 引用の情報と問い合わせの案内 (「引用と問い合わせ」)
doc/ 本書の利用者ガイドと API リファレンスの HTML (日本語・英語. 入口は doc/index.html, 英語は doc/index_en.html. ウェブブラウザでそのまま開ける)
COPYING, COPYING.LESSER ライセンス (LGPL-3.0)

 説明の md (README.md, CHANGELOG.md, SUPPORT.md, spack/README.md, python/README.md, tests/*/README.md) は英語版で, 同じ場所に日本語版 (README.ja.md など, 名前の .md の前に .ja) がある. 以下では日本語版の名前で示す.

 試験の実行方法は tests/regression/README.ja.md と tests/perf/README.ja.md に記す. 回帰試験は検証用サンプル (C++) と, C言語・Fortran・Python の API の試験 (examples/sample_c.c, examples/sample_f.f90, tests/regression/sample_py.py) からなり, MPI あり・なしと言語を選んで生成・ビルド・投入・集計できる. 同梱の設定 (tests/site_config.py) には, 本書の試験環境のほか, spack でゼロから入れた環境で流す例 (s86spack_cpu, s86spack_gpu など) と, スケジューラの無い macOS + Homebrew の例 (mac) がある.

4.2 ビルド後の確認

 ビルド後の確認には bash examples/run_quick_checks.sh を使う. クイックスタートの 4 つの例 (C++・C言語・Fortran・Python) を examples/build_examples.sh でビルドして 1 プロセスで実行し, MPI ありのビルドでは C++ の例を 2 プロセスでも実行する. 各例は厳密解との最大相対誤差が 1e-6 以下なら check: ... PASS を表示する (「プログラムの概要」). 最後に PASS n / FAIL m (SKIP k) と所要時間を 1 行で表示し, 不合格が無ければ終了コード 0 で終わる. Python の例は, parcel (と NumPy・SciPy) を import できなければ SKIP とする (不合格にしない).

 ビルド (build_examples.sh quick) は SYCL のコンパイル (C++ の例と C言語・Fortran の API のラッパ) を同時に走らせる (同時に走らせる数は BUILD_JOBS. 既定は対象の数とコア数の小さい方). ビルドに成功すると, ビルドの設定 (SYCL_TARGET, CXXFLAGS, PARCEL_MPI, コンパイラとその場所など) とソース (ヘッダ, API, 例) の cksum を examples/build/build_stamp.txt に記録する. 2 回目からは, 実行ファイルがそろい記録が今と同じならビルドを飛ばして実行だけをする (1 分かからない). 設定かソースが変わっていれば, 違う項目を表示して作り直す. --rebuild を付けると必ず作り直す.

export OMPI_CXX=acpp
bash examples/run_quick_checks.sh                 # MPI あり. 最後の行: === PASS 6 / FAIL 0 (SKIP 0)  所要 <秒> s
PARCEL_MPI=0 bash examples/run_quick_checks.sh    # MPI なし
bash examples/run_quick_checks.sh --rebuild       # 作り直す
NO_BUILD=1 bash examples/run_quick_checks.sh      # 記録を見ずに examples/build/ を実行だけする

 コンパイラ・ターゲット・LAPACK の環境変数は build_examples.sh と同じである (GPU は例えば SYCL_TARGET=--acpp-targets=cuda:sm_70). MPI の起動コマンドは MPIEXEC (既定 mpirun), MPIEXEC_NP_FLAG (既定 -n), MPI_NP (既定 2), MPIEXEC_ARGS で変える. 起動コマンドを通さないと MPI_Init できない MPI (富士通 MPI など) では MPIEXEC_ALL=1 で 1 プロセスの実行も起動コマンドを通す. 富士通の mpiexec はランクの標準出力をジョブのログに出し, check の行を読めないので, 富士通の mpiexec (MPIEXEC=mpiexec で, その実体が /opt/FJSV… にあるもの) では RC_ONLY=1 (終了コード 0 なら合格) が既定になる (外すときは RC_ONLY=0). spack で入れた場合は spack test run parcel-sycl py-parcel-sycl が同じ判定を行う (「spack によるインストール」).

 スレッド数と実行場所. OMP_NUM_THREADS が未設定なら, 計算ノード (ジョブの中) では使える論理 CPU 数をすべて, ログインノードでは 4 (使える数が 4 未満ならその数) を使う. MPI の実行では合計がそれになるようプロセス数で割る (最低 1. ログインノードで 2 プロセスなら 1 プロセス 2 スレッド). 使える論理 CPU 数は, CPU の割り当て (nproc)・cgroup の CPU の上限・ジョブのこのノードの割り当て (PBS の NCPUS, Slurm の SLURM_CPUS_ON_NODE) の最も小さいものである. 計算ノードかどうかはジョブの環境変数 (PBS の PBS_JOBID, 富士通 PJM の PJM_JOBID, Slurm の SLURM_JOB_ID) の有無で決め, QUICK_NODE=compute / QUICK_NODE=login で強制できる. 判定と使った値は最初に表示する. OMP_NUM_THREADS を設定していればその値を使う (ジョブではスケジューラが設定していることがある. PBS の ompthreads (キューの既定が 1 のことがある), 富士通 PJM の --omp thread=). Open MPI で MPIEXEC_ARGS に配置の指定 (--bind-to, --map-by) が無ければ --bind-to none を足す (Open MPI は 2 プロセス以下だと各プロセスを 1 コアに固定し, 複数のスレッドが 1 コアに詰め込まれるため).

 どこで流すか. CPU の環境はログインノードでもよい (施設の規則に従う). GPU の環境と A64FX (Odyssey) は計算ノード (短いバッチジョブか対話ジョブ) で流す (ログインノードには GPU が無く, A64FX の実行ファイルは x86 のログインノードでは動かない). GPU の環境で MPI の試験 (2 プロセス) を流すとき, このスクリプトはプロセスごとに GPU を 1 台ずつ割り当てる設定 (「1 ランクと 1 デバイスの対応」 の gpu_bind.sh のようなもの) をしないので, 2 プロセスが同じ GPU を使うことがある.

4.3 コンパイルオプション

 コンパイル時に指定するフラグを示す. ライブラリ本体 (Include/) の-Dマクロはマクロの節に示す. サンプルの実行時オプション (環境変数 PARCEL_SOLVER, PARCEL_NX, PARCEL_PRECON など) は使用方法の章で説明する.

全環境で必要なフラグ

フラグ 説明
--acpp-targets=<ターゲット> 生成するコードの種類. omp (CPU, OpenMP), omp.library-only (A64FX + 富士通コンパイラ), cuda:sm_70 (V100), cuda:sm_80 (A100), cuda:sm_90 (H100), hip:gfx942 (MI300A)
-I<lapacke.h の場所> lapacke.h のインクルードパス. 例: -I/usr/include/openblas
-l<LAPACK ライブラリ> LAPACKE を含むライブラリ. 例: -lopenblas, 富士通 -lfjlapack, PS では -l:libopenblaso.so.0
-O3 最適化. すべての環境で指定している

環境依存のフラグ

フラグ 使用環境 説明
-march=native -mtune=native s86 CPU/GPU, Miyabi-C, Miyabi-G, PS-A ホスト CPU 向けの最適化
-Xcuda-ptxas -maxrregcount=255 s86 GPU (V100) ptxas (CUDA のアセンブラ) のレジスタ数の上限を広げる. V100 で推奨. 既定の割り当てでは Jacobi 前処理などのカーネルで行列とベクトルの読み出しが分かれて直列になり, 遅くなる. spill は出ず, 計算結果は変わらない. 他の GPU には付けない (V100 のレジスタ数の指定)
-std=c++17 Odyssey 富士通コンパイラ経由のビルドで指定
-DNDEBUG -fno-math-errno -fno-trapping-math PS-B 値を変えない浮動小数点のフラグだけを用いる. -ffast-mathは double-double の誤差項と NaN の検出を壊すので使わない (付けると#errorで止まる). -fno-exceptionsは引数検査の例外と両立しないので使わない

4.4 マクロ

 PARCEL はヘッダーファイルだけのライブラリなので, 利用者のプログラムをコンパイルするときに-D<マクロ>または-D<マクロ>=<値>を付けると, ライブラリ本体 (Include/) の構成や動作を選べる. どのマクロも既定値のままで使え, 通常は何も指定しなくてよい. 目的ごとに次の 4 種類がある.

 このほかに診断・切り分け用のマクロがあるが, 通常は指定しない.

4.4.1 ビルドするソルバの取捨 (Include/parcel_solver_select.hpp)

 既定では全ソルバが有効であり, 通常は何も指定しなくてよい. 1 つの翻訳単位に全ソルバが入るためコンパイル時間が長く (A64FX では 1 構成 6〜14 分), 切り分けなどで使うソルバが決まっている場合に外すと短縮できる.

 各マクロは 1 でそのソルバを入れ, 0 で外す. 各ソルバのマクロを指定しなければPARCEL_ENABLE_ALL_SOLVERSの値 (既定 1) になるので, 何も指定しなければ全ソルバが入る. 一部のソルバだけを入れる場合はPARCEL_ENABLE_ALL_SOLVERS=0としてから, 入れるソルバを 1 にする.

マクロ 既定値 説明
PARCEL_ENABLE_ALL_SOLVERS 1 下記の各ソルバのマクロを指定しなかったときの値. 0 にすると, 1 を指定したソルバだけが入る
PARCEL_ENABLE_PCG 1 (PARCEL_ENABLE_ALL_SOLVERS の値) parcel::krylov::pcg
PARCEL_ENABLE_PBICGSTAB 1 (PARCEL_ENABLE_ALL_SOLVERS の値) parcel::krylov::pbicgstab
PARCEL_ENABLE_PGMRES 1 (PARCEL_ENABLE_ALL_SOLVERS の値) parcel::krylov::pgmres
PARCEL_ENABLE_PCAGMRES 1 (PARCEL_ENABLE_ALL_SOLVERS の値) parcel::krylov::pcagmres (QQを作らない方式CAGMRES_Q_IMPLICITを含む)
PARCEL_ENABLE_POWER 1 (PARCEL_ENABLE_ALL_SOLVERS の値) parcel::krylov::power
PARCEL_ENABLE_INVERSE_POWER 1 (PARCEL_ENABLE_ALL_SOLVERS の値) parcel::krylov::inverse_power
PARCEL_ENABLE_KS_ARNOLDI 1 (PARCEL_ENABLE_ALL_SOLVERS の値) parcel::krylov::ks_arnoldi. 0 にすると LAPACKE は不要になる (検証用サンプルを除く)

 依存関係は自動で補われる. inverse_power を有効にすると pcg と pgmres が, ks_arnoldi を有効にすると pgmres が有効になる. 1 つも有効でない場合はコンパイルエラーになる. PARCEL_ENABLE_CHOLQR_PCAGMRES というマクロは無く, 指定するとコンパイルエラー (#error) になる.

# pgmres だけを入れる (他はすべて外す)
-DPARCEL_ENABLE_ALL_SOLVERS=0 -DPARCEL_ENABLE_PGMRES=1
# ks_arnoldi だけを外す (他はすべて入れる)
-DPARCEL_ENABLE_KS_ARNOLDI=0

4.4.2 整数型

 行番号・列番号・行数・非零要素数などの整数は, 大域の添字をマクロPARCEL_INTの型で, 1 つのランクの中の添字 (デバイス上の CRS など) をマクロPARCEL_LINTの型で持つ. 既定はPARCEL_INTが 64 ビット (int64_t. MPI の通信ではMPI_INT64_T), PARCEL_LINTが 32 ビット (int32_t, MPI_INT32_T) である. この既定にした理由 (大規模な問題での桁あふれと局所カーネルの速さ) は基本構成の「整数型」に示す.

指定 PARCEL_INT PARCEL_LINT 備考
なし (既定) int64_t int32_t
-DPARCEL_LOCAL_INT64 int64_t int64_t -DPARCEL_LOCAL_INT64=0は既定と同じ
-DPARCEL_INT32 int32_t int32_t -DPARCEL_INT32=0は既定と同じ
-DPARCEL_INT int64_t int32_t PARCEL_INTを 64 ビットにする旧来の書き方. 互換のため受け付ける (値は見ない)
-DPARCEL_INTと-DPARCEL_INT32の両方 — — 矛盾するので#errorでビルドを止める
-DPARCEL_INT32と-DPARCEL_LOCAL_INT64の両方 — — ランク内の型が大域の型より広くなるので#errorでビルドを止める

 選ばれた幅はマクロPARCEL_INT_BITSとPARCEL_LINT_BITS (いずれも 64 または 32) で分かる.

 型の選び方 (扱える行列の範囲, 大規模な問題での桁あふれ, メモリ量と局所カーネルの速さへの影響, C言語・Fortran の API との関係) は基本構成の「整数型」に示す.

4.4.3 最適化

 計算 (アルゴリズムと反復回数) を変えずに速さを上げる最適化のマクロを示す. 演算カーネルのループの形を選ぶもの (前半の 8 つ) と, メモリを使って速くするもの (後半の 2 つ. 最適化オプション) がある. 各最適化の仕組み, 効果, 環境ごとの既定は「最適化」の章に, 環境ごとのコンパイルコマンドは推奨オプションに示す. 既定はメモリを少なくする設定である.

マクロ 既定値 説明
_BLOCKING_LOOP_ 0 1 で SpMV 以外の全カーネル (内積, axpy, 前処理など) をブロック化版に替える (ブロック化). A64FX 向け
_BLOCKING_LOOP_DOT_ 0 1 で縮約 (dot,dddot,max) だけをブロック化版に替える. A64FX 以外の CPU 向け. GPU では指定しない
PARCEL_SPMV_LADDER 0 1 で SpMV の内側ループを梯子状に分割する (梯子分割). AMD の GPU と A64FX 向け. NVIDIA の GPU には付けない
PARCEL_PRECON_LADDER 0 (PARCEL_SPMV_LADDER の値) Jacobi 前処理の反復ループの梯子分割. A64FX では 0 を明示する
PARCEL_GEMV_AS_AXPY 0 (_BLOCKING_LOOP_ の値) 1 で gemv を M 回の axpy に分解する (gemv の分解). 丸めの順序が変わる
PARCEL_A64FX_AXPY_C 1 1 で, 係数を値で渡す axpy と gemv の axpy 分解版を A64FX 向けに書き直した版を使う (A64FX 向けの最適化の C). 0 で書き直す前の形にする. 結果は変わらない. _BLOCKING_LOOP_のビルドでだけ働く
PARCEL_CG_FUSED 0 (_BLOCKING_LOOP_ の値) 1 でpcgの 1 反復のカーネルを融合する (xx と pp の更新, rr の更新と ⟨r,r⟩\langle r, r \rangle. A64FX 向けの最適化の D). 結果は変わらない. _BLOCKING_LOOP_のビルドでだけ 1 にできる
PARCEL_JACOBI_NODIV_UNIT 1 1 で Jacobi 前処理の右辺の準備で割る値が 1 のとき割り算を省く (A64FX 向けの最適化の E). 結果は変わらない. _BLOCKING_LOOP_のビルドでだけ働く
PARCEL_JACOBI_ROW2 0 (_BLOCKING_LOOP_ の値. PARCEL_PRECON_LADDERが 1 なら 0) 1 で前処理行列が単精度のとき Jacobi 前処理の反復を 2 行ずつ交互に処理する (A64FX 向けの最適化の F). 結果は変わらない. 倍精度の前処理行列とその場で計算する版では使わない
PARCEL_JACOBI_ONTHEFLY 1 (A64FX 向けでは 0) Jacobi 前処理 (PRECON_JACOBI) のB=DA−1RB = D_A^{-1}Rの値を持たず, 適用のたびにAAの値とDA−1D_A^{-1}から計算する. 0 で値を保持する (最適化オプション「H なし」. AAの非零の数 × 前処理行列の精度の大きさのメモリを使う). 行列スケーリング有効時, 係数行列・前処理行列・前処理の演算精度のいずれかが double-double の場合は 1 でも値を保持する. _BLOCKING_LOOP_ (または _BLOCKING_LOOP_SPMV_) が 1 の A64FX 向けのビルドでは既定が 0 になる (「メモリと速さの選択」)
PARCEL_PCG_NO_XHIST 1 pcgが解の更新をまとめる反復数 (pstep) の既定. 1 で 1 (探索方向を 1 本だけ持ち, 毎反復更新),0 で 4 (最適化オプション「G なし」. 袖付きベクトル 3 本分のメモリを使う). 実行時の環境変数PARCEL_PSTEPが優先する

4.4.4 ks_arnoldi の直交化の既定

 ks_arnoldiの Arnoldi 過程の直交化 (固有値ソルバの章の Krylov-Schur 法) は, プログラムでset_qr_algo()を呼んで選ぶ (API リファレンスのks_arnoldiのset_qr_algo()). 呼ばないときの既定は, 次のマクロでビルド時に選ぶ. 環境変数PARCEL_KS_ORTHOは読まない (設定されていると, 最初のsolver()で rank 0 が標準エラーに警告を 1 行出す. 動作は変わらない).

マクロ 既定値 説明
PARCEL_KS_ORTHO_DEFAULT 未定義 (cgs2) cgs2 (古典 Gram-Schmidt 法 2 回) または mgs (修正 Gram-Schmidt 法 2 回). PS-A 向けのビルド (spack の環境psa, バリアントks_ortho=mgs) はmgsである. 未定義なら CGS2 (QR_CGS). set_qr_algo()で指定した値が優先する

4.4.5 検査と数値演算

 誤った結果を防ぐための検査と, double-double の演算の方式を選ぶ. 既定のまま使う. 外すと誤った結果を黙って返しうるので, 理由を理解したうえでのみ指定する.

マクロ 既定値 説明
PARCEL_REQUIRE_IN_ORDER 1 set_crsMat() と各ソルバの solver() の入口で, SYCL キューが in-order であることを検査し, 違反 (キューが無い場合を含む) は std::invalid_argument を投げる. PARCEL はカーネルを sycl::event や depends_on を使わずに 1 本のキューへ順に投入し, 前のカーネルの結果を次のカーネルが読むので, in-order 実行が前提である. SYCL 2020 の既定 (out-of-order) キューでは, accessor を使わない USM カーネル同士の実行順は保証されない. 0 で検査を外す
PARCEL_NO_CRS_CHECK 0 1 で set_crsMat() (通常版と double-double の hi/lo 版) の入力の検査を外す. 検査するのは, 局所行数 n が nend-nstart+1 に等しく 1 行以上であること (0 行のランクは扱えない), rowptr[0] == 0・単調非減少・rowptr[n] == nnz であること, 全ランクの行ブロックが全体の行を隙間・重複なく覆うこと (ランクの並び順は問わない), 列番号が全体の行数の範囲にあること. 非 MPI 版は rowptr と列番号だけを調べる. 崩れていれば全ランクが同じ std::invalid_argument を投げる (文言に崩れていたランクと内容). 費用は非零要素の走査 1 回と集団通信 2 回である. 外して崩れた入力を与えると, 袖通信の未初期化の受信バッファを使って黙って誤った結果になるか, 配列の範囲外を読む
PARCEL_ALLOW_FAST_MATH 未定義 定義すると -ffast-math / -ffinite-math-only (__FAST_MATH__ / __FINITE_MATH_ONLY__) 付きのビルドを許す. 既定では parcel_sycl.hpp が #error で止める. 結合則による式の書き換えで double-double の誤差項が消え, dd が黙って倍精度に落ちる. また NaN / Inf の検査 (std::isfinite) が消され, DIVERGED_NANORINF が働かなくなる. 定義した場合, dd の精度と NaN の検出は保証しない
PARCEL_DD_NO_FMA 未定義 定義すると double-double の積の誤差なし変換 (TwoProd) を, 既定の fma によるもの (p=fma(a,b,0)p = \mathrm{fma}(a,b,0), e=fma(a,b,−p)e = \mathrm{fma}(a,b,-p)) から Dekker の分割に替える. FMA 命令を持たない CPU 向けである. GPU (CUDA) では Dekker の分割が壊れるので使わない

 -fno-exceptions も使わない. 引数の検査 (std::invalid_argument など) と両立しない.

 各環境で推奨するフラグを示す. A64FX 以外の CPU には縮約のブロック化, A64FX には全カーネルのブロック化と SpMV の梯子分割と積和の FMA へのまとめ (-ffp-contract=fast) を指定し, 実行時にOMP_WAIT_POLICY=ACTIVEとKMP_BLOCKTIME=infiniteを設定する (A64FX 向けの最適化), AMD の GPU には梯子分割を指定する. NVIDIA の GPU には梯子分割を付けず, V100 にはレジスタ数の指定を付ける.

環境 --acpp-targets カーネル最適化 LAPACKE
s86 CPU omp -D_BLOCKING_LOOP_DOT_=1 -I/usr/include/openblas -lopenblas
s86 GPU cuda:sm_70 なし (梯子分割を付けない) + -Xcuda-ptxas -maxrregcount=255 -I/usr/include/openblas -lopenblas
Odyssey omp.library-only -D_BLOCKING_LOOP_=1 -DPARCEL_SPMV_LADDER=1 -DPARCEL_PRECON_LADDER=0 + -ffp-contract=fast -I/usr/include/openblas -lfjlapack
Aquarius cuda:sm_80 なし -I/usr/include/openblas -lopenblas
Miyabi-C omp -D_BLOCKING_LOOP_DOT_=1 -I/usr/include/openblas -lopenblas
Miyabi-G cuda:sm_90 なし -I/usr/include/openblas -lopenblas
PS-A omp -D_BLOCKING_LOOP_DOT_=1 nvhpc の lapacke.h + -l:libopenblaso.so.0
PS-B hip:gfx942 -DPARCEL_SPMV_LADDER=1 -DPARCEL_PRECON_LADDER=1 nvhpc の lapacke.h + -l:libopenblaso.so.0

 各最適化の仕組みと, 環境ごとに測った効果は「最適化」の章に示す.

 以下では環境ごとにコンパイルコマンドを示す. 環境設定は「SYCL対応コンパイラのインストール方法」の章の各環境の「使用時の設定」で行う. いずれも検証用サンプル tests/verify/parcel_krylov_sample_verify.cpp を倍精度でビルドする例で, パッケージのトップディレクトリで実行する. ソルバ・問題サイズ・前処理は実行時に指定する (検証用サンプルの実行時オプション). 最大反復回数は-DMAX_ITERATIONを付けなければ 10000 (tests/verify/parcel_default.hppの既定. ライブラリの既定と同じ) で, 実行時にPARCEL_MAX_ITERで変えられる. コンパイルは MPI も GPU も使わないので, A64FX 以外はログインノードで行う. <spack のインストール先> などは各自の環境に読み替える.

4.5.1 s86 (CPU)

# 環境設定: 「SYCL対応コンパイラのインストール方法」の章の「s86」の「使用時の設定」を行う

mpicxx -O3 --acpp-targets=omp -march=native -mtune=native \
  -D_BLOCKING_LOOP_DOT_=1 \
  -I/usr/include/openblas \
  -o verify_double tests/verify/parcel_krylov_sample_verify.cpp -lopenblas

4.5.2 s86 (GPU)

# 環境設定: 「SYCL対応コンパイラのインストール方法」の章の「s86」の「使用時の設定」を行う

mpicxx -O3 --acpp-targets=cuda:sm_70 -march=native -mtune=native \
  -Xcuda-ptxas -maxrregcount=255 \
  -I/usr/include/openblas \
  -o verify_double tests/verify/parcel_krylov_sample_verify.cpp -lopenblas

4.5.3 Odyssey

 A64FX ではログインノードと計算ノードのアーキテクチャが異なるため, 計算ノードでビルドする. ビルド用のジョブスクリプトの例を示す. MPI ラッパは mpiFCC を用い, OMPI_CXX=acpp で acpp を呼ばせる. acpp は omp.library-only ターゲットで ACPP_CPU_CXX の富士通コンパイラをホストコンパイラとして用いる. LAPACKE のヘッダの場所は他の環境と同じく -I/usr/include/openblas で指定し (この指定で計算ノードでビルドできる), 実装は富士通の libfjlapack を用いる.

#!/bin/bash
#PJM -L "rscgrp=short-o"
#PJM -L "node=1"
#PJM -L "elapse=2:00:00"
#PJM -g <グループ>
#PJM --omp thread=48
#PJM -j

# 環境設定: 「SYCL対応コンパイラのインストール方法」の章の「Odyssey」の「使用時の設定」を行う

cd ${PJM_O_WORKDIR}
LINKOPT="-L$fj_root/lib64 -Wl,-rpath,$fj_root/lib64 \
  -L$sycl_root/lib -Wl,-rpath,$sycl_root/lib \
  -L$llvm_root/lib -Wl,-rpath,$llvm_root/lib -lfjlapack"

mpiFCC -O3 -std=c++17 --acpp-targets=omp.library-only \
  -D_BLOCKING_LOOP_=1 -DPARCEL_SPMV_LADDER=1 -DPARCEL_PRECON_LADDER=0 \
  -ffp-contract=fast \
  -I/usr/include/openblas \
  -o verify_double tests/verify/parcel_krylov_sample_verify.cpp ${LINKOPT}

 1 回のビルドは Xeon より長くかかり, メモリも数 GiB を要する. 1 ノードのジョブが使えるメモリは 28 GiB なので, 複数の精度構成を同時にビルドする場合は本数を制限する.

 -ffp-contract=fastは積和 (a×b+ca \times b + c) を FMA 命令にまとめさせる. 富士通コンパイラの clang モードは既定では積和をまとめない. AdaptiveCpp はACPP_OMP_CXX_FLAGSの後ろにコマンドラインの-O3を並べて富士通コンパイラに渡すので, ACPP_OMP_CXX_FLAGSの-Kfastは後ろの-O3で打ち消され, 効かない. -Kfastを後ろに-O3を置かずに渡すなどして fast-math を効かせると, double-double と NaN の検出が壊れるため, PARCEL はビルドを#errorで止める (「-ffast-math を使わない」). -ffp-contract=fastはコマンドラインに置けば富士通コンパイラまで届く. Odyssey の 1 ノード (4 ランク × 12 スレッド, NX=256, pcg + Jacobi 前処理) で, 1 反復が 3 % 速くなった (SpMV は 10 %, axpy の本体は 25 %). 反復回数は変わらず, 結果は最後の桁が変わる (残差で相対 1e-11 程度). FMA は積を丸めずに和を取るので, 付けないビルドとはビット単位では一致しない. 結果をそろえたい場合は-ffp-contract=offにする. double-double の関数の中はInclude/ddlib.hppが FMA を禁じたままである (この節の最後の段落).

 A64FX 向けのビルド (-D_BLOCKING_LOOP_=1) では, Jacobi 前処理のBBの値を保持する (「メモリと速さの選択」の「H なし」) のが既定である (PARCEL_JACOBI_ONTHEFLYの既定 0. 指定は要らない). A64FX ではその場の計算 (非零ごとの掛け算と対角の判定) が前処理の時間に表れ, Odyssey の 1 ノード (NX=256, pcg + Jacobi 前処理) で値を保持すると前処理の区間が 0.77 倍, 収束までの総時間が 0.81 倍になる. そのかわりメモリがAAの非零 1 個あたり前処理行列の精度の大きさ (倍精度で 8 バイト) 増える. メモリを減らしたい場合は-DPARCEL_JACOBI_ONTHEFLY=1を明示する.

 実行時には, OpenMP のスレッドを待ち合わせの間も休ませないOMP_WAIT_POLICY=ACTIVEとKMP_BLOCKTIME=infiniteを設定する (推奨. ライブラリの既定ではないので, ジョブの環境で設定する). Odyssey の 1 ノード (4 ランク × 12 スレッド, 1 CMG に 1 ランク) で, 問題の大きさによらない 1 反復の固定費が 5.2 ms から 3.0 ms に減る. 装置あたりの行数が少ない場合に効く. 待っているスレッドもコアを使い続けるので, コアを取り合う配置 (1 ノードに他のプロセスを同居させるなど) では逆効果になる. このビルドで有効になる axpy の書き直しとpcgのカーネルの融合とあわせて, 効果と注意は「A64FX 向けの最適化」に示す.

 2026-10-10 より前のコードでは, double-double の演算のための FMA の禁止 (#pragma clang fp contract(off)) が富士通コンパイラではddlib.hppの範囲で戻らず, 以降の全カーネルで FMA 命令が使われていなかった (富士通コンパイラの clang モードはfloat_controlの push / pop を知らない). 今のコードは禁止を double-double の関数の中に限り, 他のカーネルではコンパイラの指定 (上の-ffp-contract=fast) どおり FMA を使う. 倍精度などの結果は以前のビルドと最後の桁で変わる.

4.5.4 Aquarius

# 環境設定: 「SYCL対応コンパイラのインストール方法」の章の「Aquarius」の「使用時の設定」を行う

mpicxx -O3 --acpp-targets=cuda:sm_80 \
  -I/usr/include/openblas \
  -o verify_double tests/verify/parcel_krylov_sample_verify.cpp -lopenblas

4.5.5 Miyabi-C

# 環境設定: 「SYCL対応コンパイラのインストール方法」の章の「Miyabi-C」の「使用時の設定」を行う

mpicxx -O3 --acpp-targets=omp -march=native -mtune=native \
  -D_BLOCKING_LOOP_DOT_=1 \
  -I/usr/include/openblas \
  -o verify_double tests/verify/parcel_krylov_sample_verify.cpp -lopenblas

4.5.6 Miyabi-G

# 環境設定: 「SYCL対応コンパイラのインストール方法」の章の「Miyabi-G」の「使用時の設定」を行う

mpicxx -O3 --acpp-targets=cuda:sm_90 -march=native -mtune=native \
  -I/usr/include/openblas \
  -o verify_double tests/verify/parcel_krylov_sample_verify.cpp -lopenblas

4.5.7 PS-A

 PS の計算ノードには /usr/include/openblas/lapacke.h が無い (ログインノードにのみ存在する). また MKL は mkl_lapacke.h しか持たない. そこで nvhpc が持つ lapacke.h をヘッダとして借り, 実装は OS の OpenBLAS (OpenMP 版 libopenblaso) に解決させる. OpenBLAS 側のスレッドが PARCEL の OpenMP と入れ子にならないよう, OPENBLAS_NUM_THREADS=1 を設定する. MPI は Intel MPI なので I_MPI_CXX でも acpp を指定する.

# 環境設定: 「SYCL対応コンパイラのインストール方法」の章の「PS-A」の「使用時の設定」を行う

mpicxx -O3 --acpp-targets=omp -march=native -mtune=native \
  -D_BLOCKING_LOOP_DOT_=1 \
  -I/system/apps/rhel9/dev/nvhpc/25.3/Linux_x86_64/25.3/compilers/include/lp64 \
  -o verify_double tests/verify/parcel_krylov_sample_verify.cpp -l:libopenblaso.so.0

4.5.8 PS-B

 LAPACKE の扱いは PS-A と同じである.

# 環境設定: 「SYCL対応コンパイラのインストール方法」の章の「PS-B」の「使用時の設定」を行う

mpicxx -O3 --acpp-targets=hip:gfx942 \
  -DNDEBUG -fno-math-errno -fno-trapping-math \
  -DPARCEL_SPMV_LADDER=1 -DPARCEL_PRECON_LADDER=1 \
  -I/system/apps/rhel9/dev/nvhpc/25.3/Linux_x86_64/25.3/compilers/include/lp64 \
  -o verify_double tests/verify/parcel_krylov_sample_verify.cpp -l:libopenblaso.so.0

4.5.9 C言語・Fortran のプログラム

 C言語・Fortran の API を使うプログラムは, ラッパ capi/wrapper_parcel_sycl.cpp を上の各環境のmpicxxのコマンドと同じフラグ (--acpp-targets, カーネル最適化, LAPACKE) でコンパイルし, C・Fortran の main と SYCL 対応コンパイラでリンクする. --acpp-targets はラッパのコンパイルとリンクでそろえる. acpp (clang) は PIE としてリンクするので, gcc・gfortran で作るオブジェクトには -fPIE を付ける. s86 CPU (Open MPI) の例を示す. 他の環境では 1 行目のフラグをその環境のものに替える.

# 環境設定: 「SYCL対応コンパイラのインストール方法」の章の「s86」の「使用時の設定」を行う
FLAGS="-O3 --acpp-targets=omp -march=native -mtune=native -D_BLOCKING_LOOP_DOT_=1"
mpicxx ${FLAGS} -I/usr/include/openblas -c capi/wrapper_parcel_sycl.cpp -o wrapper_parcel_sycl.o

# C言語
mpicc  -O2 -fPIE -Icapi -c prog.c -o prog.o
mpicxx --acpp-targets=omp -o prog prog.o wrapper_parcel_sycl.o -lopenblas -lm

# Fortran (PARCEL のモジュールを先にコンパイルする)
mpif90 -O2 -fPIE -c capi/parcel_sycl_mod.f90 -o parcel_sycl_mod.o
mpif90 -O2 -fPIE -c prog.f90 -o prog.o
mpicxx --acpp-targets=omp -o prog prog.o parcel_sycl_mod.o wrapper_parcel_sycl.o \
       $(mpif90 --showme:link) -L$(dirname $(mpif90 -print-file-name=libgfortran.so)) -lgfortran -lopenblas

4.5.10 macOS (Homebrew)

 Homebrew で入れた環境 (「SYCL対応コンパイラのインストール方法」の「macOS (Homebrew)」) では, --acpp-targets=omp.library-only と縮約だけのブロック化 (-D_BLOCKING_LOOP_DOT_=1. 他の CPU と同じ) を用い, LAPACKE は Homebrew の OpenBLAS を指定する. Homebrew の AdaptiveCpp では--acpp-targets=ompも同じコンパイルになる. -march=nativeは要らない (付けても速さは同じ). 実行時は mpirun -n <並列数> --bind-to none で起動する. 次の例は クイックスタートの 4 言語のプログラムで確かめた.

eval "$(/opt/homebrew/bin/brew shellenv)"
export OMPI_CXX=acpp
B=/opt/homebrew
T="--acpp-targets=omp.library-only"
LAPACK_INC="-I$B/opt/openblas/include"
LAPACK_LIB="-L$B/opt/openblas/lib -lopenblas -Wl,-rpath,$B/opt/openblas/lib"
FC_RT="-L$B/opt/gcc/lib/gcc/current -lgfortran -Wl,-rpath,$B/opt/gcc/lib/gcc/current"

# C++ (MPI あり. MPI なしは mpicxx を acpp に替え -DPARCEL_MPI=0 を付ける)
mpicxx -O3 $T -D_BLOCKING_LOOP_DOT_=1 ${LAPACK_INC} \
  -o verify_double tests/verify/parcel_krylov_sample_verify.cpp ${LAPACK_LIB}

# C言語・Fortran (MPI あり)
mpicxx -O3 $T -D_BLOCKING_LOOP_DOT_=1 ${LAPACK_INC} -c capi/wrapper_parcel_sycl.cpp -o wrapper_parcel_sycl.o
mpicc  -O2 -Icapi -c prog.c -o prog_c.o
mpicxx $T -o prog_c prog_c.o wrapper_parcel_sycl.o ${LAPACK_LIB}
mpif90 -O2 -c capi/parcel_sycl_mod.f90 -o parcel_sycl_mod.o
mpif90 -O2 -c prog.f90 -o prog_f.o
mpicxx $T -o prog_f prog_f.o parcel_sycl_mod.o wrapper_parcel_sycl.o $(mpif90 --showme:link) ${FC_RT} ${LAPACK_LIB}
mpirun -n 4 --bind-to none ./prog_c

 macOS の gfortran の実行時ライブラリは .dylib なので, 場所 ($B/opt/gcc/lib/gcc/current) を-Lと-Wl,-rpathで与える. python/envs/mac_brew.sh を読み込むと, 同じ値が環境変数 (SYCL_TARGET, CXXFLAGS, LAPACK_INC, LAPACK_LIB, FC_LINK) に入り, examples/build_examples.sh でサンプルを作れる. Python のパッケージは「Python のパッケージ」に示す.

4.6 MPI の有無の既定

 PARCEL を MPI ありでビルドするか, MPI なしの 1 プロセス版でビルドするかは, マクロ PARCEL_MPI (1: あり, 0: なし) で決まる. 既定は使い方によって次のように異なる.

使い方 PARCEL_MPIの既定 決めている場所 MPI なし / ありにする指定
C++ (Include/parcel_sycl.hppをインクルード) 1 (MPI あり) Include/のヘッダ -DPARCEL_MPI=0を付ける
C言語 (capi/parcel_sycl_c.h) 1 (MPI あり) parcel_sycl_c.hとラッパ ラッパと main の両方に-DPARCEL_MPI=0を付ける
Fortran (capi/parcel_sycl_mod.f90) 1 (MPI あり) ラッパ (モジュールは MPI の有無によらない) ラッパに-DPARCEL_MPI=0を付け, use mpiを代用モジュールで満たす
examples/build_examples.sh 1 (MPI あり) 環境変数PARCEL_MPI PARCEL_MPI=0 bash examples/build_examples.sh
Python (python/. pip) 0 (MPI なし) python/CMakeLists.txt -C cmake.define.PARCEL_MPI=1で MPI あり
spack (parcel-sycl, py-parcel-sycl) 0 (MPI なし. バリアント~mpi) レシピのバリアントmpi +mpiで MPI あり

 C++・C言語・Fortran の既定が MPI ありなのは, v1.0 と同じ使い方 (MPI のラッパでコンパイルしmpirunで起動する) のプログラムをそのまま動かすためである. Python と spack の既定が MPI なしなのは, MPI の無い環境 (手元の計算機, macOS など) でもすぐに入れて試せるようにするためである. MPI ありの版を使う場合は, 上の指定で明示する. C言語・Fortran では, ラッパと main で指定が食い違うとコミュニケータの引数の型が合わず, 正しく動かない (リンクでは検出されない) ので, 両方を同じ指定でビルドする. C++ はヘッダだけのライブラリなので, 利用者のプログラムの指定がそのまま使われる. どちらの版も計算は同じで, MPI ありの版を 1 プロセスで実行した結果と MPI なしの版の結果はビット単位で一致する.

4.7 MPI なしのビルド

 -DPARCEL_MPI=0 を付けると, MPI を使わない 1 プロセス版をビルドできる. mpi.h を読まず, MPI のライブラリもリンクしないので, MPI のコンパイララッパ (mpicxx) ではなく SYCL 対応コンパイラ (acpp など) で直接コンパイルし, mpirun を使わずに実行する. 指定しない場合 (既定) は MPI ありである. 計算は MPI ありのビルドを 1 プロセスで実行した場合と同じで, 結果はビット単位で一致する.

acpp -O3 --acpp-targets=omp -march=native -DPARCEL_MPI=0 \
  -I/usr/include/openblas -o quick_start examples/quick_start.cpp -lopenblas
./quick_start

# examples/ の 4 本 (C言語・Fortran は gcc・gfortran でコンパイルする)
PARCEL_MPI=0 bash examples/build_examples.sh

 C言語・Fortran のプログラムを手でビルドする場合は, ラッパと C の main の両方に-DPARCEL_MPI=0を付け, MPI のラッパ (mpicxx, mpicc, mpif90) の代わりに acpp, gcc, gfortran を使う. Fortran のuse mpiは 1 プロセス用の代用モジュール examples/sample_f_mpi_stub.f90 (MPI_Init, MPI_Comm_rank, MPI_Comm_size, MPI_Finalize などを 1 プロセスとして実装したもの) で満たす. コマンドの例はクイックスタートの「C言語」と「Fortran」の「MPI なし」に示す.

 利用者のプログラムは MPI ありと同じ書き方で動く. 違いは次のとおりである.


4.8 Python のパッケージ

 Python のパッケージ parcel (配布パッケージの python/) は, PARCEL の C++ のライブラリを直接呼ぶネイティブ層 (libparcel_py.so) をソースからビルドして入れる. 必要なものは, PARCEL をビルドできる環境 (SYCL 対応コンパイラの章の「使用時の設定」), Python 3.8 以上と NumPy である. 行列を作るには SciPy が便利であり, 回帰試験の Python の試験 (tests/regression/sample_py.py) も SciPy を使う. ネイティブ層は AdaptiveCpp でビルドする. 既定は MPI なしの 1 プロセス版であり, ビルドの設定 PARCEL_MPI=1 で MPI ありの版になる. 入れ方は次の 3 通りである. 使い方は使用方法の Python に示す.

4.8.1 環境ごとの設定

 ネイティブ層は環境 (SYCL のターゲットと MPI の有無) ごとにビルドする. ビルドの設定は pip の-C cmake.define.<名前>=<値>で与える (「ビルドの設定」). 本書の試験環境で用いた値を次に示す (推奨オプションと同じ). 空欄は既定値のままでよい.

環境 PARCEL_TARGET PARCEL_KERNEL_FLAGS PARCEL_EXTRA_FLAGS
s86 (CPU), Miyabi-C, PS-A (omp) (-D_BLOCKING_LOOP_DOT_=1)
s86 (V100) cuda:sm_70 (-DPARCEL_SPMV_LADDER=0 -DPARCEL_PRECON_LADDER=0. 梯子分割なし) -Xcuda-ptxas -maxrregcount=255
Aquarius (A100) cuda:sm_80 (同上)
Miyabi-G (GH200) cuda:sm_90 (同上)
PS-B (MI300A) hip:gfx942 (-DPARCEL_SPMV_LADDER=1 -DPARCEL_PRECON_LADDER=1)
macOS (Apple シリコン) + Homebrew omp.library-only (-D_BLOCKING_LOOP_DOT_=1)

 括弧の値は既定値 (PARCEL_KERNEL_FLAGS はターゲットから決まる値) である. LAPACKE の場所 (LAPACKE_INCLUDE_DIR, LAPACK_LIBS) は環境に合わせて与える (PS-A・PS-B では -l:libopenblaso.so.0 など. 推奨オプションの各環境の節). ビルド・インストール・実行のいずれも, 同じ環境 (SYCL 対応コンパイラの章の「使用時の設定」. AdaptiveCpp・LAPACK・MPI のライブラリが見つかる状態) で行う.

 macOS では, Homebrew で入れた環境 (「SYCL対応コンパイラのインストール方法」の「macOS (Homebrew)」) で python/envs/mac_brew.sh を読み込むと, 上の表の値と Homebrew の OpenBLAS の場所が環境変数に設定されるので, その後で下の pip または直接のビルドを行う.

4.8.2 MPI なし (既定)

 pip は python/ で実行する. pip はビルドに scikit-build-core と CMake 3.18 以上を使う (無ければ取得する) ので, パッケージの置き場に接続できる必要がある. venv の pip は先に更新しておく (古い pip はビルドの設定を渡す -C を受け付けないことがある). ログインノードで実行してよく, 1〜2 分かかる.

python3 -m venv $HOME/venv_parcel
$HOME/venv_parcel/bin/python -m pip install -U pip
$HOME/venv_parcel/bin/python -m pip install scipy           # 任意. 行列を作るのに便利 (parcel の依存は NumPy だけ)
cd python
$HOME/venv_parcel/bin/python -m pip install . -C cmake.define.PARCEL_TARGET=cuda:sm_70 \
    -C "cmake.define.PARCEL_EXTRA_FLAGS=-Xcuda-ptxas -maxrregcount=255"     # s86 (V100) の例

 ネイティブ層は acpp で直接ビルドし, MPI のライブラリをリンクしない.

 pip を使わない場合は, ネイティブ層を直接ビルドし, 環境変数 PARCEL_PY_LIB にその場所を, PYTHONPATH に python/ を与える (パッケージのトップディレクトリで実行する. 回帰試験の Python のジョブもこの形で, tests/regression/sub_build_lang_<環境>.sh が bin/<環境>/libparcel_py.so を作る).

acpp -O3 --acpp-targets=omp -DPARCEL_MPI=0 -march=native -mtune=native -D_BLOCKING_LOOP_DOT_=1 \
     -fPIC -shared -IInclude -I/usr/include/openblas -o libparcel_py.so python/src/parcel_py.cpp -lopenblas
PYTHONPATH=python PARCEL_PY_LIB=$PWD/libparcel_py.so python script.py

 入ったことは次のように確かめる. parcel.has_mpi() は MPI ありの版なら True を返す. parcel.build_info() はビルドの設定を, parcel.device_name() は使われるデバイスの名前を返す.

$HOME/venv_parcel/bin/python -c "import parcel; print(parcel.has_mpi(), parcel.build_info(), parcel.device_name())"

 Python の API の試験 tests/regression/sample_py.py は, C言語の examples/sample_c.c と同じ問題・項目・判定 (7 種のソルバ, QQ を作らない pcagmres の 2 通り, ks_arnoldi の shift-invert など) を Python から行う. 回帰試験の言語 python として流せるほか (「パッケージの構成」), 単独でも動く. 引数は NX である.

PARCEL_TEST_FROM_SOURCE=1 PARCEL_PY_LIB=$PWD/libparcel_py.so python tests/regression/sample_py.py 16   # パッケージの python/ を読む
python tests/regression/sample_py.py 16                                                                # インストールした parcel を読む

4.8.3 MPI あり

 ビルドの設定 PARCEL_MPI=1 を与えると, ネイティブ層を MPI の C++ ラッパ (既定 mpicxx) でビルドする. ラッパが中で acpp を呼ぶよう, OMPI_CXX=acpp (Open MPI) などを先に設定しておく. mpi4py は任意であり, 使う場合は同じ MPI でビルドしたものを venv に入れる.

export OMPI_CXX=acpp
python3 -m venv $HOME/venv_parcel_mpi                       # MPI なしの版とは別の venv にする
$HOME/venv_parcel_mpi/bin/python -m pip install -U pip
cd python
$HOME/venv_parcel_mpi/bin/python -m pip install . -C cmake.define.PARCEL_MPI=1

 pip を使わない場合は, 上のacppの行をmpicxxにし, -DPARCEL_MPI=0を外す. 実行は「MPI ありでの実行」に示す.

 試験の状況: pip で入れたパッケージとソースからビルドしたものの両方が, MPI ありの版で s86 (CPU, V100), Miyabi-C, Miyabi-G, PS-A, PS-B, Aquarius のすべての項目に合格した. MPI なしの版は s86, Aquarius, macOS (Homebrew. MPI ありの版も) で確認した. spack で入れた py-parcel-sycl の確認は「spack によるインストール」に示す.

4.8.4 ビルドの設定

 pip の -C cmake.define.<名前>=<値> で与える名前を次に示す (python/CMakeLists.txt の先頭に同じ一覧がある). 値を与えなければ右の列の既定値になる.

名前 内容 既定値
PARCEL_MPI 0 は MPI なしの 1 プロセス版, 1 は MPI あり 0
PARCEL_TARGET --acpp-targets の値 omp
PARCEL_KERNEL_FLAGS カーネル最適化のマクロ PARCEL_TARGET から決める (omp は -D_BLOCKING_LOOP_DOT_=1, hip は梯子分割の 2 つ, cuda は梯子分割なし)
PARCEL_HOST_FLAGS ホスト向けの最適化 -march=native -mtune=native
PARCEL_EXTRA_FLAGS その他のフラグ なし
PARCEL_INCLUDE_DIR PARCEL の Include/ python/ と同じ階層の Include/
LAPACKE_INCLUDE_DIR lapacke.h の場所 /usr/include/openblas
LAPACK_LIBS LAPACK のライブラリ -lopenblas
PARCEL_MPICXX C++ コンパイラ MPI なしは acpp, MPI ありは mpicxx


4.9 spack によるインストール

 配布パッケージの spack/ には, PARCEL を spack で入れるためのレシピと, spack の取得から LLVM・AdaptiveCpp・OpenBLAS・Python, PARCEL までをゼロから入れるスクリプトがある. 説明の原文は spack/README.ja.md (英語版は spack/README.md) である. spack は 1.x (パッケージリポジトリの API v2.2) を対象とする.

4.9.1 レシピ

パッケージ 中身
parcel-sycl ヘッダ (include/), C言語の API (lib/libparcel_sycl_c.so と include/parcel_sycl_c.h), Fortran のモジュール (include/parcel_sycl_mod.mod と lib/libparcel_sycl_f.a)
py-parcel-sycl Python のパッケージ parcel (python/ を scikit-build-core でビルドする. 「Python のパッケージ」)

 バリアントは両方に共通である.

バリアント 既定 意味
mpi off MPI あり (既定は MPI なしの 1 プロセス版)
cuda + cuda_arch=<n> off --acpp-targets=cuda:sm_<n>. cuda_arch=70 (V100) では -Xcuda-ptxas -maxrregcount=255 を自動で付ける
rocm + amdgpu_target=<gfx> off --acpp-targets=hip:<gfx>
(cuda・rocm のどちらも無し) --acpp-targets=omp (CPU)
native on -march=native -mtune=native
kernel auto カーネル最適化 (「最適化」). auto (CPU は blocking_dot, AMD の GPU (+rocm) は ladder, NVIDIA の GPU (+cuda) は none, +fjはa64fx), blocking_dot, a64fx, ladder, none
fj off A64FX 向け: ホスト側を富士通コンパイラ (FCC) でコンパイルし, Fortran のモジュールを frt で作る (Odyssey の定義 wis_ody で確認). -std=c++17 -ffp-contract=fastを付ける (推奨オプション)
capi (parcel-sycl のみ) on C言語・Fortran の API をビルドする
scipy (py-parcel-sycl のみ) on SciPy も入れる (DistributedCSR.from_scipy()・from_global() と examples/quick_start.py が使う. pip の parcel[scipy] に当たる)
ks_ortho cgs2 ks_arnoldiの直交化の既定 (「ks_arnoldi の直交化の既定」). mgsで-DPARCEL_KS_ORTHO_DEFAULT=mgsを付ける (PARCEL_CXXFLAGSにも入る). プログラムがset_qr_algo()で指定した値が優先する. py-parcel-syclは同じ値のparcel-syclでビルドする

 既存の spack の環境に足す場合は, spack develop で手元の配布パッケージを使う.

spack -e <環境> repo add <パッケージ>/spack/spack_repo/parcel
spack -e <環境> config add "concretizer:unify:when_possible"          # CPU 版と GPU 版などを並べるとき
spack -e <環境> develop --no-clone --path <パッケージ> parcel-sycl@1.2.0
spack -e <環境> develop --no-clone --path <パッケージ> py-parcel-sycl@1.2.0
spack -e <環境> add "parcel-sycl@1.2.0 ~mpi ~cuda ~rocm" "py-parcel-sycl@1.2.0 ~mpi ~cuda ~rocm"                    # CPU
spack -e <環境> add "parcel-sycl@1.2.0 ~mpi +cuda cuda_arch=70" "py-parcel-sycl@1.2.0 ~mpi +cuda cuda_arch=70"     # GPU
spack -e <環境> concretize -f && spack -e <環境> install

 使うときは, 構成を指定して spack load する. spack load parcel-sycl は, 利用者のプログラムを PARCEL と同じ設定でコンパイルするための PARCEL_CXXFLAGS (ターゲット, 最適化, MPI の有無, ヘッダの場所) と PARCEL_LDFLAGS (実行時に要るライブラリ (LLVM の libomp, AdaptiveCpp, LAPACK, MPI) の RPATH と LAPACK) を設定する. MPI ありの版では OMPI_CXX=acpp なども設定するので, mpicxx で同じようにコンパイルする. MPI のラッパ経由では libomp の RPATH が付かないので, PARCEL_LDFLAGS を必ず付ける. C言語・Fortran の API のヘッダ (parcel_sycl_c.h, parcel_sycl_mod.mod) とライブラリの場所は spack load では設定されないので, spack location -i で調べて -I, -L, -Wl,-rpath に与える.

spack env activate <環境>
spack load parcel-sycl+cuda py-parcel-sycl+cuda                   # 構成を指定して読む
acpp $PARCEL_CXXFLAGS -O3 -o prog prog.cpp $PARCEL_LDFLAGS        # C++
P=$(spack location -i parcel-sycl+cuda)                           # C言語 (MPI なしの版): 場所は自分で与える
gcc -I$P/include -o prog prog.c -L$P/lib -lparcel_sycl_c -Wl,-rpath,$P/lib
python script.py                                                  # Python

 注意点を次に示す.

4.9.2 配布 tarball から入れる

 レシピは配布 tarball の url と sha256 を持つ. url は GitHub の Release に置く tarball (https://github.com/parcel-jaea/PARCEL-release/releases/download/v1.2.0/parcel_sycl-1.2.0.tar.gz) を指し, sha256 は tools/make_tarball.py --pin がレシピに書く (「配布物の確認」). spack develop を使わなければ, spack は url から tarball を取得する (parcel-sycl と py-parcel-sycl は同じ tarball を使う). 計算機が外部に接続できないときは, tarball を spack の mirror の形 (<mirror>/_source-cache/archive/<sha256 の先頭 2 文字>/<sha256>.tar.gz) に置き, spack mirror add で登録する. spack は取得した tarball をレシピの sha256 と照合し, 違えば止まる. sha256 は spack のハッシュに入るので, 書き直すと (spack develop で使う場合も) PARCEL が作り直される. 手順は spack/README.ja.md の「配布 tarball から入れる」に示す.

4.9.3 構成の選び方

 入れる構成は, パッケージ (parcel-sycl, py-parcel-sycl) とバリアントの組合せ (仕様) で選ぶ. 目的ごとの仕様の例を示す (版の@1.2.0は省略した).

目的 仕様
CPU, MPI なし (C++・C言語・Fortran) parcel-sycl ~mpi ~cuda ~rocm
CPU, MPI あり parcel-sycl +mpi ~cuda ~rocm
NVIDIA の GPU (A100 の例) parcel-sycl ~mpi +cuda cuda_arch=80
NVIDIA の GPU, MPI あり parcel-sycl +mpi +cuda cuda_arch=80
AMD の GPU (MI300A) parcel-sycl ~mpi +rocm amdgpu_target=gfx942
C++ (ヘッダ) だけ. C言語・Fortran の API を作らない parcel-sycl ~capi ~mpi ~cuda ~rocm
Python も使う 同じ構成のpy-parcel-syclも並べる (例: py-parcel-sycl ~mpi ~cuda ~rocm)

 ゼロから入れる方法では, 入れる構成はspack/stack/envs/<環境>/spack.yamlのspecs:に並べたものである. 同梱の定義は, その環境で使える構成をすべて並べている (例えば s86 は CPU / GPU × MPI なし / あり × parcel-sycl / py-parcel-sycl の 8 行). 構成を絞る・変えるときは, install_stack.shを実行する前にspecs:を書き換える. 例えば CPU・MPI ありの C++・C言語・Fortran と Python だけを入れる場合は次のようにする. 入れた後に書き換えた場合も, 同じコマンドでinstall_stack.shを流し直せば, 解決し直して足りないものだけを入れる.

spack:
  specs:
  - parcel-sycl@1.2.0 +mpi ~cuda ~rocm         # CPU・MPI あり (C++・C言語・Fortran)
  - py-parcel-sycl@1.2.0 +mpi ~cuda ~rocm      # 同じ構成の Python

4.9.4 ゼロから入れる

 既存の spack を使わず, spack の取得から PARCEL までを spack/stack/install_stack.sh の 1 本で入れる. 引数は環境の名前 (spack/stack/envs/ の下のディレクトリ名), 入れ先, 並列数である.

bash spack/stack/install_stack.sh s86 $HOME/parcel_stack 16           # <環境> <入れ先> [並列数]
bash spack/stack/check_stack.sh $HOME/parcel_stack $HOME/parcel_check  # ログインノードでの確認
. $HOME/parcel_stack/setup.sh                                          # 使うとき
spack load parcel-sycl+mpi+cuda py-parcel-sycl+mpi+cuda

4.9.5 用意した環境

envs/ 環境 入れる構成 既存品
s86 s86 (Xeon + V100) CPU / GPU (cuda_arch=70) × MPI なし / あり GCC 9.5.0, CUDA 12.6, Open MPI 4.1.6
miyc Miyabi-C CPU × MPI なし / あり GCC 11.4.1, Open MPI 4.1.6
miyg Miyabi-G GPU (cuda_arch=90) × MPI なし / あり GCC 11.4.1, CUDA 12.6, Open MPI 4.1.6 (CUDA 版)
psa PS-A CPU × MPI なし / あり (ks_ortho=mgs: ks_arnoldiの直交化の既定が MGS2) GCC 11.5.0, Intel MPI 2021.18
psb PS-B GPU (amdgpu_target=gfx942) × MPI なし / あり GCC 11.5.0, ROCm 6.3.3, Open MPI 5.0.7 (ROCm 版)
wis_aqu Aquarius GPU (cuda_arch=80) × MPI なし / あり GCC 8.3.1 (GCC 12 を作るためだけに使う), CUDA 12.2, Open MPI 4.1.1
wis_ody Odyssey CPU (+fj) × MPI なし / あり GCC 8.3.1, 富士通のコンパイラ・MPI・LAPACK (tcsds-1.2.43)
generic 上記以外の Linux (雛形) CPU × MPI なし (MPI あり・NVIDIA の GPU はコメントを外して足す) 書き換えて使う (GCC, MPI, CUDA)

4.9.6 試験環境以外の計算機

 上の 7 環境以外の Linux の計算機では, 雛形 spack/stack/envs/generic/ を写して書き換え, install_stack.sh で入れる. 雛形は s86 と Miyabi-C の定義にならって作ったものである. Ubuntu 24.04 (WSL2. OS の GCC 13.3.0, Open MPI 4.1.6, NVIDIA のリポジトリの CUDA 12.6, RTX A6000) で, 下の手順のとおりに書き換えて CPU・GPU (cuda_arch=86) × MPI なし・ありの 8 構成を入れ, check_stack.sh, クイックスタート (C++・C言語・Python), 検証用サンプル (pcg・pgmres・ks_arnoldi) が合格した. Rocky Linux 9.8 (RHEL 9 互換. WSL2. OS の GCC 11.5.0, Open MPI 4.1.1, NVIDIA のリポジトリの CUDA 12.6) でも同じ 8 構成を入れ, 同じ試験が合格した. RHEL 系の OS の Open MPI は, ヘッダを含めて 1 つのディレクトリに並べてから登録する (「MPI と CUDA を登録する」).

cp -r spack/stack/envs/generic spack/stack/envs/mysite           # 写して書き換える
CONCRETIZE_ONLY=1 bash spack/stack/install_stack.sh mysite $HOME/parcel_stack   # 解決だけを試す
bash spack/stack/install_stack.sh mysite $HOME/parcel_stack 16                  # 入れる

 書き換える箇所はspack.yamlの先頭のコメントに手順として書いてある.