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

1 クイックスタート

 1 次元 Laplace 作用素の差分行列 (三重対角行列) を係数とする連立一次方程式 Ax=bAx = b を共役勾配法で解く最小のプログラムで, SYCL 対応コンパイラの導入からビルド, 実行までを示す. 同じ問題を C++・C言語・Fortran・Python の 4 つの言語で解き, それぞれ MPI なし (1 プロセス) と MPI あり (複数プロセス) の作り方と動かし方を示す. 本書に出てくる計算機・装置の名前 (s86, V100 など) と略語は用語集にまとめている.

1.1 プログラムの概要

 解く問題は次のとおりである. 4 つの言語のプログラムはいずれもこの問題を解き, 同じ結果を出す.

 右辺 bb は反転対称 (bi=bn−1−ib_i = b_{n-1-i}) で, AA の固有ベクトルのうち n/2n/2 本とだけ成分を持つので, 共役勾配法は丸め誤差が無ければちょうど n/2=500n/2 = 500 反復で厳密解 xi=(i+1)(n−i)/2x_i = (i+1)(n-i)/2 (x0=n/2=500x_0 = n/2 = 500) に到達する. どの言語のプログラムも, 収束状態・反復回数・残差とx0x_0を表示し, 全成分について厳密解との相対誤差 |xi−(i+1)(n−i)/2|/((i+1)(n−i)/2)|x_i - (i+1)(n-i)/2| / ((i+1)(n-i)/2) の最大を求めて, 1e-6 以下なら check: ... PASS と表示する (MPI ありでは各ランクの担当行の最大をランク間で集める). 収束しないか誤差がしきい値を超えると FAIL を表示して終了コード 1 で終わる. しきい値は, 条件数 (約 4.1e5) と収束判定値 1e-9 からの最悪の見積もり 4e-4 よりずっと小さいが, 実際の誤差は丸め誤差の程度 (0〜1.3e-15) で, 解き方の誤りは桁違いに大きい誤差になるので区別できる. 4 つの言語の例をまとめてビルド・実行して合否を出すには bash examples/run_quick_checks.sh を使う (インストールの「ビルド後の確認」).

 プログラムの流れはどの言語でも同じである.

  1. 行をランクに分ける. 各ランクは連続した行 (行ブロック) を受け持つ. MPI なしでは 1 プロセスが全行を受け持つ.
  2. 受け持つ行の係数行列を CRS 形式 (行ポインタ・列番号・値) で作る. 列番号は大域の番号で渡す.
  3. ソルバの設定 (収束判定値, 最大反復回数) をして解く. 設定しない項目はライブラリの既定値になる.
  4. 収束状態を確かめる.

 MPI なしとありで, プログラムの書き方はほとんど変わらない. MPI ありでは各ランクが自分の担当行だけを作り, 全ランクが同じ関数を同じ設定で呼ぶ (集団操作). MPI なしは 1 プロセスが全体を持つ. どちらで作るかはビルドの指定 (PARCEL_MPI) で選ぶ (インストールの「MPI の有無の既定」).

 必要なものは次のとおりである.

1.2 SYCL 対応コンパイラの導入

 PARCEL はヘッダーファイルだけのライブラリで, SYCL 対応コンパイラでコンパイルして使う. v1.2 では AdaptiveCpp を用いる.

 導入の経路は環境によって次のように選ぶ.

環境 経路 説明
本書の試験環境 (s86, Odyssey, Aquarius, Miyabi-C, Miyabi-G, PS-A, PS-B) install_stack.sh (ゼロから入れる), または既存の spack に AdaptiveCpp を入れる 環境の定義 spack/stack/envs/<環境>/ が同梱されている. 既存の spack に入れる手順は「SYCL対応コンパイラのインストール方法」の章の各環境の節
上記以外の Linux (RHEL 系・Ubuntu 系, Windows の WSL2) install_stack.sh と雛形 generic, または spack に AdaptiveCpp を入れる Ubuntu 24.04 と Rocky Linux 9 (いずれも WSL2) で確かめた. 「一般的な Linux」
macOS Homebrew 「macOS (Homebrew)」
Python だけを使う pip (python/でpip install .), または spack のpy-parcel-sycl AdaptiveCpp と LAPACKE は上のいずれかで先に入れる. 「Python のパッケージ」

 主な経路の使い方を示す.

bash spack/stack/install_stack.sh s86 $HOME/parcel_stack 16     # <環境> <入れ先> [並列数]
. $HOME/parcel_stack/setup.sh                                   # 使うとき (毎回)
spack load parcel-sycl~mpi~cuda~rocm py-parcel-sycl~mpi~cuda~rocm      # CPU 版・MPI なしの例
brew install adaptivecpp open-mpi openblas gcc numpy scipy

 以下の各言語の例は, CPU (AdaptiveCpp の OpenMP バックエンド) で, LAPACKE が/usr/include/openblasにある Linux の環境 (s86 など) を想定し, パッケージのトップディレクトリで実行する. 環境変数とモジュールは環境ごとに異なるので, 「SYCL対応コンパイラのインストール方法」の章の各環境の「使用時の設定」を先に行う. macOS + Homebrew の場合のフラグはインストールの「macOS (Homebrew)」に示す. CPU の実行ファイルは LLVM の OpenMP ランタイム (libomp.so) を使うが, acpp はその場所を実行ファイルに埋め込まない. 試験環境の「使用時の設定」はLD_LIBRARY_PATHに LLVM のlib/を加えてこれを解決している. 自分で用意した環境では, 実行時にLD_LIBRARY_PATHに LLVM のlib/を加えるか, リンク時に-Wl,-rpath,<LLVM の lib>を付ける (どちらも無いと OS のlibompを読むか, 見つからずに起動できない). Fortran の実行時ライブラリ (libgfortran) の場所も-Lで与える (例ではgfortran -print-file-nameで調べている). GPU (NVIDIA) では --acpp-targets=cuda:sm_70 のように対象を変える. プログラムは変えなくてよい. V100 (sm_70) では-Xcuda-ptxas -maxrregcount=255も付けることを推奨する (推奨オプション).

1.2.1 GCC 以外のコンパイラの環境

 以下の例は C言語・Fortran の main を gcc・gfortran (または Open MPI の mpicc・mpif90) でコンパイルする. 標準のコンパイラが GCC でない環境でも同じ手順で使える. 試験環境での組み合わせを示す. 各環境の詳しいフラグはインストールの「推奨オプション」にある.

標準のコンパイラ (試験環境) C++ (PARCEL 本体) C言語・Fortran の main MPI のラッパ 注意
GCC (s86 など多くの Linux) acpp (LLVM 18 の clang) gcc・gfortran Open MPI のmpicxx・mpicc・mpif90 (OMPI_CXX=acpp) —
富士通コンパイラ (Odyssey) acpp --acpp-targets=omp.library-only. カーネルを含む全体を富士通 FCC (clang モード. ACPP_CPU_CXXで指定) がコンパイルする 富士通 fcc・frt mpiFCC (OMPI_CXX=acpp), mpifcc, mpifrt fcc・frt には-Kopenmpを付ける (使用方法の「Fortran」). ログインノードと計算ノードのアーキテクチャが違うので, ビルドは計算ノードで行う (「Odyssey」)
Intel oneAPI (PS-A) acpp (LLVM 18 の clang. サイトのintel・intelmpiモジュールを読んだ環境で使う) gcc・gfortran (Intel MPI のmpicc・mpif90) Intel MPI のmpicxx (I_MPI_CXX=acpp) MPI の Fortran ライブラリはmpif90 -showで調べる (「PS-A」)
Apple clang (macOS) acpp --acpp-targets=omp.library-only. 全体を Apple clang がコンパイルする clang (C), gfortran (Homebrew のgcc) Open MPI (Homebrew) のmpicxx・mpicc・mpif90 (OMPI_CXX=acpp) 縮約だけのブロック化 (-D_BLOCKING_LOOP_DOT_=1) を付ける. -march=nativeは要らない (付けても速さは同じ). mpirun --bind-to noneで起動する (インストールの「macOS (Homebrew)」)

 以下の実行例のスレッド数は, 実行結果を得た macOS + Homebrew の計算機 (Apple M4, 10 コア) に合わせて, MPI なしは 8 スレッド, MPI ありは 4 ランク × 2 スレッドとしている. 自分の環境では, ランク数 × スレッド数がコア数を超えないように変える. 実行結果は, この 2 通りで実行したもので, 表示は両者で同じだった. 残差の値は環境と並列数によって丸めの桁が変わる (例えば s86 CPU の 4 ランクでは真の残差が 2.49e-14) が, 反復回数 500 とx0=500x_0 = 500は変わらない. 途中の反復の表示と時間の内訳は省略した.

1.3 C++

1.3.1 プログラム

 ソースは examples/quick_start.cpp である. MPI なしとありの違いは #if PARCEL_MPI の 4 か所だけである.

#include <algorithm>
#include <cmath>
#include <cstdio>
#include <vector>
#include "../Include/parcel_sycl.hpp"

int main(int argc, char *argv[]) {
#if PARCEL_MPI
  MPI_Init(&argc, &argv);
#else
  (void)argc; (void)argv;
#endif
  {
    // 既定のデバイス (--acpp-targets で決まる)。in-order キューを使う
    //   (PARCEL はカーネルを event なしで順に投入するため、in-order でないとソルバが例外を投げる)
    sycl::queue q{sycl::default_selector_v, sycl::property::queue::in_order{}};
#if PARCEL_MPI
    parcel::comm comm(MPI_COMM_WORLD, &q);
#else
    parcel::comm comm(&q);                          // MPI なし: rank 0, 1 プロセス
#endif
    const int myrank = comm.mpi_rank(), nproc = comm.mpi_size();

    // 行の分割: 各ランクが連続した行を持つ (端数は最終ランク)
    const PARCEL_INT n_global = 1000;
    const PARCEL_INT nstart = (n_global / nproc) * myrank;
    const PARCEL_INT nend   = (myrank == nproc - 1) ? n_global - 1 : nstart + n_global / nproc - 1;
    const PARCEL_INT n      = nend - nstart + 1;

    // 担当行の CRS (行ポインタは局所 0 始まり, 列番号は大域 0 始まり)
    std::vector<PARCEL_INT> rowptr(n + 1, 0), col;
    std::vector<double> val;
    for (PARCEL_INT i = nstart; i <= nend; i++) {
      if (i > 0)            { col.push_back(i - 1); val.push_back(-1.0); }
      col.push_back(i);       val.push_back( 2.0);
      if (i < n_global - 1) { col.push_back(i + 1); val.push_back(-1.0); }
      rowptr[i - nstart + 1] = (PARCEL_INT)col.size();
    }
    parcel::matrix<parcel_double> A(&q);
    A.set_crsMat<double>(&comm, nstart, nend, n, col.size(), rowptr.data(), col.data(), val.data());

    std::vector<double> x_h(n, 0.0), b_h(n, 1.0);
    parcel::vector<parcel_double> x(n, &q), b(n, &q);
    x.setValue(x_h.data());
    b.setValue(b_h.data());

    // 共役勾配法 (演算はすべて倍精度)
    parcel::krylov::pcg<parcel_double, parcel_double, parcel_double, parcel_double> cg;
    cg.set_tolerance(1.0e-9);                       // 相対残差 ||r|| / ||b||
    cg.set_max_iteration(10000);
    q.wait();
    cg.solver<parcel_double, parcel_double, parcel_double,
              parcel_double, parcel_double, parcel_double>(A, x, b);
    x.getValue(x_h.data());
    q.wait();

    // 厳密解との比較. 行列は境界の外の値を 0 とした (Dirichlet 境界) 差分 -x[i-1] + 2 x[i] - x[i+1] = 1 なので,
    //   厳密解は x[i] = (i + 1) (n_global - i) / 2 (i は大域 0 始まり. x[0] = n_global / 2, 中央で最大 約 n_global^2 / 8).
    //   全成分の相対誤差 |x[i] - exact| / exact の最大を各ランクの担当行で求め, ランクの最大を集める.
    // しきい値 1e-6: 条件数は cot^2(pi / (2 (n_global + 1))) = 約 4.1e5 で, tolerance 1e-9 からの最悪の見積もり
    //   (相対誤差 <= 条件数 x 相対残差) は 4e-4. 実際はそれよりずっと小さい: b = 1 は中央に対して対称なので Krylov 部分空間は
    //   500 次元で尽き, pcg は 500 反復で残差がほぼ 0 になって, 誤差は丸め誤差の程度 (s86 の CPU・GPU, 1・2 ランクで 0〜1.3e-15).
    //   解き方の誤り (行列・分割・通信の誤り) は桁違いに大きい誤差になるので, 1e-6 で区別できる.
    const double err_limit = 1.0e-6;
    double err_local = 0.0;
    for (PARCEL_INT k = 0; k < n; k++) {
      const double i = (double)(nstart + k);
      const double exact = 0.5 * (i + 1.0) * ((double)n_global - i);
      double e = std::fabs(x_h[k] - exact) / exact;
      if (!(e == e)) e = HUGE_VAL;                  // NaN は無限大として扱う (不合格にする)
      err_local = std::max(err_local, e);
    }
    double err_max = err_local;
#if PARCEL_MPI
    MPI_Allreduce(&err_local, &err_max, 1, MPI_DOUBLE, MPI_MAX, MPI_COMM_WORLD);
#endif
    const bool ok = cg.is_converged() && err_max <= err_limit;

    // 収束状態と判定 (全ランクで同じ値)
    if (myrank == 0) {
      std::printf("reason = %d (%s), iterations = %d, residual = %.3e, true residual = %.3e\n",
                  (int)cg.get_converged_reason(),
                  parcel::krylov::converged_reason_name(cg.get_converged_reason()),
                  (int)cg.get_iterations(), cg.get_residual(), cg.get_true_residual());
      std::printf("x[0] = %.6f (exact %.6f)\n", x_h[0], 0.5 * 1.0 * (double)n_global);
      std::printf("check: max relative error = %.3e (limit %.1e) %s\n", err_max, err_limit, ok ? "PASS" : "FAIL");
      std::fflush(stdout);                          // MPI_Abort の前に出力を出し切る
    }
#if PARCEL_MPI
    if (!ok) { MPI_Abort(MPI_COMM_WORLD, 1); }
  }
  MPI_Finalize();
#else
    if (!ok) { return 1; }
  }
#endif
  return 0;
}

 SYCL キューは必ず in-order キュー (sycl::property::queue::in_order{} を付けて作る) とする. PARCEL はカーネルを sycl::event による依存関係を付けずに 1 本のキューへ順に投入し, 前のカーネルが書いたベクトルを次のカーネルが読むので, 投入順に実行されることを前提にしている. in-order でないキューを渡すと set_crsMat() と各ソルバの solver() が std::invalid_argument を投げる.

 精度のテンプレート引数は省略でき, 省略した精度は倍精度 (parcel_double) になる. 上のプログラムの行列・ベクトル・ソルバはparcel::matrix<> A(&q);, parcel::vector<> x(n, &q);, parcel::krylov::pcg<> cg;, cg.solver(A, x, b);と書いても同じである (「精度構成」). 収束判定値と最大反復回数を設定しない場合の既定はそれぞれ 1.0e-8 と 10000 である.

1.3.2 ビルドと実行 (MPI なし)

 -DPARCEL_MPI=0 を付けて SYCL 対応コンパイラ (acpp) で直接コンパイルし, mpirun を使わずに実行する.

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

1.3.3 ビルドと実行 (MPI あり)

 MPI のラッパ (mpicxx) の中で acpp を呼ぶよう OMPI_CXX=acpp (Open MPI の場合) を設定してコンパイルし, mpirun で起動する. PARCEL_MPI の既定は 1 なので指定は要らない.

export OMPI_CXX=acpp
mpicxx -O3 --acpp-targets=omp -march=native -I/usr/include/openblas \
       -o quick_start examples/quick_start.cpp -lopenblas
OMP_NUM_THREADS=2 mpirun -n 4 ./quick_start

 OpenMP バックエンドでは環境変数OMP_PROC_BINDを設定しない. 設定すると全スレッドが 1 コアに集まり, 大幅に遅くなる環境がある (「SYCL対応コンパイラのインストール方法」の章).

1.3.4 実行結果

 最初の行はライブラリが表示する収束状態, 残りの 3 行はプログラムが表示したものである.

 converged_reason = 1 (CONVERGED_RTOL) , its = 500 , residual = 1.161602e-15 , true_residual = 1.183245e-13
reason = 1 (CONVERGED_RTOL), iterations = 500, residual = 1.162e-15, true residual = 1.183e-13
x[0] = 500.000000 (exact 500.000000)
check: max relative error = 1.252e-15 (limit 1.0e-06) PASS

1.4 C言語

1.4.1 プログラム

 C言語からは capi/parcel_sycl_c.h をインクルードし, parcel_solve_linear() を呼ぶ. 設定は構造体 parcel_options に入れ (parcel_options_init() で既定値を入れてから必要な項目だけ変える), 収束状態は parcel_result で受け取る. 行番号などの整数は 64 ビットの parcel_int である. MPI なしでは, コミュニケータの引数 (PARCEL_C_COMM) は int になり, 値は使われない. ソースは examples/quick_start_c.c である.

#include <math.h>
#include <stdio.h>
#include <stdlib.h>
#include "parcel_sycl_c.h"

int main(int argc, char *argv[]) {
#if PARCEL_MPI
  MPI_Init(&argc, &argv);
  int myrank, nproc;
  MPI_Comm_rank(MPI_COMM_WORLD, &myrank);
  MPI_Comm_size(MPI_COMM_WORLD, &nproc);
  PARCEL_C_COMM comm = MPI_COMM_WORLD;
#else
  int myrank = 0, nproc = 1;
  PARCEL_C_COMM comm = 0;                 /* MPI なしでは使われない */
#endif
  /* 行の分割: 各ランクが連続した行を持つ (端数は最終ランク) */
  const parcel_int n_global = 1000;
  const parcel_int nstart = (n_global / nproc) * myrank;
  const parcel_int nend   = (myrank == nproc - 1) ? n_global - 1 : nstart + n_global / nproc - 1;
  const parcel_int n      = nend - nstart + 1;

  /* 担当行の CRS (行ポインタは局所 0 始まり, 列番号は大域 0 始まり) */
  parcel_int *rowptr = malloc((n + 1) * sizeof(parcel_int));
  parcel_int *col    = malloc(3 * n * sizeof(parcel_int));
  double *val = malloc(3 * n * sizeof(double));
  double *b   = malloc(n * sizeof(double));
  double *x   = calloc(n, sizeof(double));
  parcel_int nnz = 0;
  rowptr[0] = 0;
  for (parcel_int i = nstart; i <= nend; i++) {
    if (i > 0)            { col[nnz] = i - 1; val[nnz++] = -1.0; }
    col[nnz] = i;           val[nnz++] =  2.0;
    if (i < n_global - 1) { col[nnz] = i + 1; val[nnz++] = -1.0; }
    rowptr[i - nstart + 1] = nnz;
    b[i - nstart] = 1.0;
  }

  /* 共役勾配法 (前処理なし, 倍精度) */
  parcel_options opt;
  parcel_options_init(&opt);              /* 既定値を入れてから必要な項目だけ変える */
  opt.tolerance     = 1.0e-9;             /* 相対残差 ||r|| / ||b|| */
  opt.max_iteration = 10000;
  parcel_result res;
  int rc = parcel_solve_linear(PARCEL_SOLVER_PCG, &opt, comm, n, nstart, n_global, nnz,
                               rowptr, col, val, b, x, &res);

  /* 厳密解との比較. 行列は境界の外の値を 0 とした (Dirichlet 境界) 差分 -x[i-1] + 2 x[i] - x[i+1] = 1 なので,
   *   厳密解は x[i] = (i + 1) (n_global - i) / 2 (i は大域 0 始まり). 全成分の相対誤差の最大を各ランクの担当行で求め,
   *   ランクの最大を集める. しきい値 1e-6 の根拠は quick_start.cpp を参照 (条件数 約 4.1e5, tolerance 1e-9). */
  const double err_limit = 1.0e-6;
  double err_local = 0.0, err_max;
  for (parcel_int k = 0; k < n; k++) {
    const double i = (double)(nstart + k);
    const double exact = 0.5 * (i + 1.0) * ((double)n_global - i);
    double e = fabs(x[k] - exact) / exact;
    if (!(e == e)) e = HUGE_VAL;          /* NaN は無限大として扱う (不合格にする) */
    if (e > err_local) err_local = e;
  }
  err_max = err_local;
#if PARCEL_MPI
  MPI_Allreduce(&err_local, &err_max, 1, MPI_DOUBLE, MPI_MAX, MPI_COMM_WORLD);
#endif
  const int ok = (rc == PARCEL_OK && res.converged_reason > 0 && err_max <= err_limit);
  if (myrank == 0) {
    printf("rc = %d, reason = %d, iterations = %d, residual = %.3e, true residual = %.3e\n",
           rc, res.converged_reason, res.iterations, res.residual, res.true_residual);
    printf("x[0] = %.6f (exact %.6f)\n", x[0], 0.5 * (double)n_global);
    printf("check: max relative error = %.3e (limit %.1e) %s\n", err_max, err_limit, ok ? "PASS" : "FAIL");
  }
  free(rowptr); free(col); free(val); free(b); free(x);
#if PARCEL_MPI
  MPI_Finalize();
#endif
  return ok ? 0 : 1;
}

1.4.2 ビルドと実行 (MPI なし)

 C言語の API の実装 (ラッパ capi/wrapper_parcel_sycl.cpp) を SYCL 対応コンパイラでコンパイルし, C の main と SYCL 対応コンパイラでリンクする. ラッパと main の両方に -DPARCEL_MPI=0 を付ける (食い違うとコミュニケータの引数の型が合わない). acpp (clang) は PIE としてリンクするので, gcc で作るオブジェクトには -fPIE を付ける.

acpp -O3 --acpp-targets=omp -march=native -DPARCEL_MPI=0 -I/usr/include/openblas \
     -c capi/wrapper_parcel_sycl.cpp -o wrapper_parcel_sycl.o
gcc  -O2 -fPIE -DPARCEL_MPI=0 -Icapi -c examples/quick_start_c.c -o quick_start_c.o
acpp --acpp-targets=omp -o quick_start_c quick_start_c.o wrapper_parcel_sycl.o -lopenblas
OMP_NUM_THREADS=8 ./quick_start_c

1.4.3 ビルドと実行 (MPI あり)

 ラッパを mpicxx (中身は acpp) で, main を mpicc でコンパイルし, mpicxx でリンクする.

export OMPI_CXX=acpp
mpicxx -O3 --acpp-targets=omp -march=native -I/usr/include/openblas \
       -c capi/wrapper_parcel_sycl.cpp -o wrapper_parcel_sycl.o
mpicc  -O2 -fPIE -Icapi -c examples/quick_start_c.c -o quick_start_c.o
mpicxx --acpp-targets=omp -o quick_start_c quick_start_c.o wrapper_parcel_sycl.o -lopenblas
OMP_NUM_THREADS=2 mpirun -n 4 ./quick_start_c

 OpenMP バックエンドでは環境変数OMP_PROC_BINDを設定しない. 設定すると全スレッドが 1 コアに集まり, 大幅に遅くなる環境がある (「SYCL対応コンパイラのインストール方法」の章).

1.4.4 実行結果

 最初の行はライブラリが表示する収束状態, 残りの 3 行はプログラムが表示したものである.

 converged_reason = 1 (CONVERGED_RTOL) , its = 500 , residual = 1.161602e-15 , true_residual = 1.183245e-13
rc = 0, reason = 1, iterations = 500, residual = 1.162e-15, true residual = 1.183e-13
x[0] = 500.000000 (exact 500.000000)
check: max relative error = 1.252e-15 (limit 1.0e-06) PASS

1.5 Fortran

1.5.1 プログラム

 Fortran からはモジュール parcel_sycl_mod (capi/parcel_sycl_mod.f90) を use し, parcel_solve_linear() を呼ぶ. 設定は派生型 parcel_options に入れ (parcel_options_init で既定値を入れてから必要な項目だけ変える), 収束状態は parcel_result で受け取る. この例では index_base = 1 として, 行ポインタ・列番号・担当行の先頭 (nstart) を Fortran の習慣どおり 1 始まりで渡す. 整数は integer(parcel_int_kind) (64 ビット) である. MPI なしでは, use mpi を 1 プロセス用の代用モジュール (examples/sample_f_mpi_stub.f90) で満たすので, プログラムは変えなくてよい. ソースは examples/quick_start_f.f90 である.

program quick_start_f
  use mpi
  use iso_c_binding
  use parcel_sycl_mod
  implicit none
  integer(parcel_int_kind), parameter :: n_global = 1000
  integer(parcel_int_kind) :: nstart, nend, n, nnz, i
  integer(parcel_int_kind), allocatable :: rowptr(:), col(:)
  real(c_double), allocatable :: val(:), b(:), x(:)
  type(parcel_options) :: opt
  type(parcel_result)  :: res
  integer :: myrank, nproc, ierr, rc
  ! 厳密解との比較のしきい値. 根拠は quick_start.cpp を参照 (条件数 約 4.1e5, tolerance 1e-9)
  real(c_double), parameter :: err_limit = 1.0d-6
  real(c_double) :: xi, exact, e, err_local, err_max
  logical :: ok

  call MPI_Init(ierr)
  call MPI_Comm_rank(MPI_COMM_WORLD, myrank, ierr)
  call MPI_Comm_size(MPI_COMM_WORLD, nproc, ierr)

  ! 行の分割: 各ランクが連続した行を持つ (端数は最終ランク). 番号は 0 始まりで計算する
  nstart = (n_global / nproc) * myrank
  if (myrank == nproc - 1) then
     nend = n_global - 1
  else
     nend = nstart + n_global / nproc - 1
  end if
  n = nend - nstart + 1

  ! 担当行の CRS (index_base = 1: 行ポインタ・列番号・nstart を 1 始まりで渡す)
  allocate(rowptr(n + 1), col(3 * n), val(3 * n), b(n), x(n))
  nnz = 0
  rowptr(1) = 1
  do i = nstart, nend
     if (i > 0) then
        nnz = nnz + 1; col(nnz) = i;     val(nnz) = -1.0d0     ! 列 i-1 (0 始まり) = i (1 始まり)
     end if
     nnz = nnz + 1;    col(nnz) = i + 1; val(nnz) =  2.0d0
     if (i < n_global - 1) then
        nnz = nnz + 1; col(nnz) = i + 2; val(nnz) = -1.0d0
     end if
     rowptr(i - nstart + 2) = nnz + 1
  end do
  b = 1.0d0
  x = 0.0d0

  ! 共役勾配法 (前処理なし, 倍精度)
  call parcel_options_init(opt)
  opt%index_base    = 1
  opt%tolerance     = 1.0d-9
  opt%max_iteration = 10000
  rc = parcel_solve_linear(PARCEL_SOLVER_PCG, opt, MPI_COMM_WORLD, n, nstart + 1, n_global, nnz, &
       rowptr, col, val, b, x, res)

  ! 厳密解との比較. 行列は境界の外の値を 0 とした (Dirichlet 境界) 差分 -x(i-1) + 2 x(i) - x(i+1) = 1 なので,
  !   厳密解は 0 始まりの大域番号 i で x = (i + 1) (n_global - i) / 2. 全成分の相対誤差の最大を各ランクの担当行で求め,
  !   ランクの最大を集める
  err_local = 0.0d0
  do i = nstart, nend
     xi = dble(i)
     exact = 0.5d0 * (xi + 1.0d0) * (dble(n_global) - xi)
     e = abs(x(i - nstart + 1) - exact) / exact
     if (e /= e) e = huge(e)                ! NaN は最大の値として扱う (不合格にする)
     err_local = max(err_local, e)
  end do
  call MPI_Allreduce(err_local, err_max, 1, MPI_DOUBLE_PRECISION, MPI_MAX, MPI_COMM_WORLD, ierr)
  ok = rc == PARCEL_OK .and. res%converged_reason > 0 .and. err_max <= err_limit
  if (myrank == 0) then
     write(*, '(a,i0,a,i0,a,i0,a,es10.3,a,es10.3)') 'rc = ', rc, ', reason = ', res%converged_reason, &
          ', iterations = ', res%iterations, ', residual = ', res%residual, ', true residual = ', res%true_residual
     write(*, '(a,f12.6,a,f12.6,a)') 'x(1) = ', x(1), ' (exact ', 0.5d0 * dble(n_global), ')'
     if (ok) then
        write(*, '(a,es9.3,a,es7.1,a)') 'check: max relative error = ', err_max, ' (limit ', err_limit, ') PASS'
     else
        write(*, '(a,es9.3,a,es7.1,a)') 'check: max relative error = ', err_max, ' (limit ', err_limit, ') FAIL'
     end if
  end if
  call MPI_Finalize(ierr)
  if (.not. ok) stop 1
end program quick_start_f

1.5.2 ビルドと実行 (MPI なし)

 Fortran の API の実装 (ラッパ capi/wrapper_parcel_sycl.cpp. C++ で書かれている) を -DPARCEL_MPI=0 を付けて SYCL 対応コンパイラでコンパイルし, 代用の mpi モジュール, PARCEL のモジュール, main の順に gfortran でコンパイルして, SYCL 対応コンパイラでリンクする. acpp (clang) は PIE としてリンクするので, gfortran で作るオブジェクトには -fPIE を付ける. リンク時には Fortran の実行時ライブラリ (-lgfortran) を加える.

acpp -O3 --acpp-targets=omp -march=native -DPARCEL_MPI=0 -I/usr/include/openblas \
     -c capi/wrapper_parcel_sycl.cpp -o wrapper_parcel_sycl.o
gfortran -O2 -fPIE -c examples/sample_f_mpi_stub.f90 -o sample_f_mpi_stub.o
gfortran -O2 -fPIE -c capi/parcel_sycl_mod.f90 -o parcel_sycl_mod.o
gfortran -O2 -fPIE -c examples/quick_start_f.f90 -o quick_start_f.o
acpp --acpp-targets=omp -o quick_start_f quick_start_f.o parcel_sycl_mod.o sample_f_mpi_stub.o \
     wrapper_parcel_sycl.o -L$(dirname $(gfortran -print-file-name=libgfortran.so)) -lgfortran -lopenblas
OMP_NUM_THREADS=8 ./quick_start_f

1.5.3 ビルドと実行 (MPI あり)

 モジュールと main を mpif90 でコンパイルし, mpicxx でリンクする. リンク時には MPI の Fortran ライブラリと Fortran の実行時ライブラリを加える (--showme:link は Open MPI の機能). 富士通 Fortran (frt, mpifrt) では -Kopenmp を付ける (使用方法の Fortran). MPI なしの手順を同じディレクトリで行った後は, 代用モジュールが作ったmpi.modを先に消す. 残っているとuse mpiが MPI の本物のモジュールでなくこれを読み, リンクで__mpi_MOD_mpi_initなどが見つからなくなる.

export OMPI_CXX=acpp
rm -f mpi.mod                     # MPI なしの手順で作った代用モジュール
mpicxx -O3 --acpp-targets=omp -march=native -I/usr/include/openblas \
       -c capi/wrapper_parcel_sycl.cpp -o wrapper_parcel_sycl.o
mpif90 -O2 -fPIE -c capi/parcel_sycl_mod.f90 -o parcel_sycl_mod.o
mpif90 -O2 -fPIE -c examples/quick_start_f.f90 -o quick_start_f.o
mpicxx --acpp-targets=omp -o quick_start_f quick_start_f.o parcel_sycl_mod.o wrapper_parcel_sycl.o \
       $(mpif90 --showme:link) -L$(dirname $(mpif90 -print-file-name=libgfortran.so)) -lgfortran -lopenblas
OMP_NUM_THREADS=2 mpirun -n 4 ./quick_start_f

 OpenMP バックエンドでは環境変数OMP_PROC_BINDを設定しない. 設定すると全スレッドが 1 コアに集まり, 大幅に遅くなる環境がある (「SYCL対応コンパイラのインストール方法」の章).

1.5.4 実行結果

 最初の行はライブラリが表示する収束状態, 残りの 3 行はプログラムが表示したものである.

 converged_reason = 1 (CONVERGED_RTOL) , its = 500 , residual = 1.161602e-15 , true_residual = 1.183245e-13
rc = 0, reason = 1, iterations = 500, residual =  1.162E-15, true residual =  1.183E-13
x(1) =   500.000000 (exact   500.000000)
check: max relative error = 1.252E-15 (limit 1.0E-06) PASS

1.6 Python

1.6.1 プログラム

 Python からはパッケージ parcel を import する. 行列は SciPy の CSR 行列から parcel.DistributedCSR で作り, parcel.solve() で解く. 同じスクリプトが MPI なしの版とありの版の両方で動く (MPI ありでは from_global() が各ランクの担当行を切り出す). 精度は倍精度だけである. ソースは examples/quick_start.py である.

import numpy as np
import scipy.sparse as sp
import parcel

n_global = 1000
G = sp.diags([-1.0, 2.0, -1.0], [-1, 0, 1], shape=(n_global, n_global), format="csr")
A = parcel.DistributedCSR.from_global(G)          # このランクの担当行を切り出す (MPI なしでは全行)
b = np.ones(A.n_local)
x, info = parcel.solve(A, b, method="pcg", tol=1e-9, maxiter=10000)   # 前処理なし, 倍精度

# 厳密解との比較. 行列は境界の外の値を 0 とした (Dirichlet 境界) 差分 -x[i-1] + 2 x[i] - x[i+1] = 1 なので,
#   厳密解は x[i] = (i + 1) (n_global - i) / 2 (i は大域 0 始まり). 全成分の相対誤差の最大を各ランクの担当行で求め,
#   ランクの最大を集める. しきい値 1e-6 の根拠は quick_start.cpp を参照 (条件数 約 4.1e5, tolerance 1e-9)
err_limit = 1.0e-6
i = np.arange(A.row_start, A.row_start + A.n_local, dtype=float)
exact = 0.5 * (i + 1.0) * (n_global - i)
rel = np.abs(x - exact) / exact
rel[~np.isfinite(rel)] = np.inf                   # NaN は無限大として扱う (不合格にする)
err_max = A.comm.allreduce(float(rel.max()), op="max")
ok = info.converged and err_max <= err_limit
if A.comm.rank == 0:
    print(f"reason = {info.reason}, iterations = {info.iterations}, "
          f"residual = {info.residual:.3e}, true residual = {info.true_residual:.3e}")
    print(f"x[0] = {x[0]:.6f} (exact {0.5 * n_global:.6f})")
    print(f"check: max relative error = {err_max:.3e} (limit {err_limit:.1e}) {'PASS' if ok else 'FAIL'}")
if not ok:
    raise SystemExit(1)

1.6.2 インストールと実行 (MPI なし)

 パッケージは環境ごとにネイティブ層をソースからビルドして入れる. 既定は MPI なしの版である. spack で入れた場合 (前節) は spack load py-parcel-sycl~mpi... で使える. pip で入れる場合は python/ で次のようにする (詳しくはインストールの「Python のパッケージ」).

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 . && cd ..     # CPU (omp) の既定の設定
OMP_NUM_THREADS=8 $HOME/venv_parcel/bin/python examples/quick_start.py

1.6.3 インストールと実行 (MPI あり)

 ビルドの設定 PARCEL_MPI=1 を与えて入れ, mpirun で起動する. 全ランクが同じスクリプトを実行する.

export OMPI_CXX=acpp
python3 -m venv $HOME/venv_parcel_mpi && $HOME/venv_parcel_mpi/bin/python -m pip install -U pip scipy
cd python && $HOME/venv_parcel_mpi/bin/python -m pip install . -C cmake.define.PARCEL_MPI=1 && cd ..
OMP_NUM_THREADS=2 mpirun -n 4 $HOME/venv_parcel_mpi/bin/python examples/quick_start.py

 OpenMP バックエンドでは環境変数OMP_PROC_BINDを設定しない. 設定すると全スレッドが 1 コアに集まり, 大幅に遅くなる環境がある (「SYCL対応コンパイラのインストール方法」の章).

1.6.4 実行結果

 Python のパッケージは, ライブラリが表示する途中経過を出さない (rank 0 がスクリプトのprintで表示する).

reason = converged, iterations = 500, residual = 1.162e-15, true residual = 1.183e-13
x[0] = 500.000000 (exact 500.000000)
check: max relative error = 1.252e-15 (limit 1.0e-06) PASS

1.7 次に読む節

したいこと 節
どのソルバ・前処理を使うか決める 「ソルバの選び方」の章
前処理を付ける 「前処理」の章, set_precon_algo()
精度を下げて速くする (混合精度) 「使用方法」C++ の「精度の指定」
GPU で動かす 「GPU で動かす」
自分の問題の行列を渡す 「自分の行列を渡す」
計算ノードのジョブで流す 「ジョブで流す」
固有値を求める 「固有値ソルバ」の章, examples/example_pcg_ks.cpp
C / Fortran から呼ぶ 「使用方法」の C言語 / Fortran
Python から呼ぶ 「使用方法」の Python
収束しないときに調べる API リファレンスの「共通メンバ関数」(get_converged_reason() ほか), 「数値精度と再現性」の章