Skip to content

add-app.md

Latest commit

 

History

History
724 lines (572 loc) · 34.7 KB

add-app.md

File metadata and controls

724 lines (572 loc) · 34.7 KB
Raw

アプリ追加手順（開発者向け）

このドキュメントは、Benchkit に新しいアプリ（プログラム）を追加する手順を開発者向けにまとめたものです。 サンプルアプリ qws を参考に、新しいアプリ <code> を追加して PR を作成するまでを説明します。

このガイドでの app 担当の責務

app 担当は、アプリ固有の build / run / result emission / app-side estimation declaration を主に担当します。 拠点の queue や runner の運用設定は config/system.csv / config/queue.csv 側の責務であり、推定 package の model metadata や fallback policy は scripts/estimation/ 側の責務です。

つまり、programs/<code>/ では次を決めます。

  • どの source を取得し、どう build するか
  • どの system / node / process / thread 条件で走らせたいか
  • run.sh からどの FOM、section、overlap、source_info を出すか
  • 推定を使う場合、estimate.sh でどの top-level package と section / overlap package を選ぶか

既存の programs/* とこのガイドを参照して追加してください。

目次

  1. リポジトリの準備
  2. アプリの基本構成
  3. 設定ファイルの作成
  4. ビルドスクリプトの作成
  5. 実行スクリプトの作成
  6. ローカルテスト
  7. バッチジョブテスト
  8. PR作成

1. リポジトリの準備

Fork と Clone

# GitHub で https://github.com/RIKEN-RCCS/benchkit を Fork
git clone https://github.com/<yourname>/benchkit.git
cd benchkit

作業用ブランチの作成

git checkout -b add-<code>
# 例: git checkout -b add-myapp

2. アプリの基本構成

ディレクトリ構成

programs/<code>/
├── build.sh    # ビルドスクリプト
├── run.sh      # 実行スクリプト
└── list.csv    # 実行条件定義

サンプルのコピー

cp -pr programs/qws/ programs/<code>
cd programs/<code>

3. 設定ファイルの作成

list.csv - 実行条件定義

同一システムで異なるノード数・プロセス数の組み合わせを定義可能：

system,enable,nodes,numproc_node,nthreads,elapse
# Fugaku での複数設定例
Fugaku,yes,1,4,12,0:10:00
Fugaku,yes,2,4,12,0:20:00
# MiyabiG/MiyabiC での設定例
MiyabiG,yes,1,1,72,0:10:00
MiyabiC,yes,1,1,112,0:10:00
# RC系での設定例
RC_DGXSP,yes,1,1,20,0:10:00
RC_GENOA,yes,1,1,96,0:10:00
RC_FX700,yes,1,4,12,0:10:00

パラメータ説明：

  • system: 実行システム名（config/system.csvと対応）
  • enable: ジョブの有効/無効（yes または no）
  • nodes: ノード数
  • numproc_node: ノードあたりプロセス数
  • nthreads: スレッド数
  • elapse: 実行時間制限

Note: list.csv は「アプリごとの実験条件」だけを書くファイルです。mode と queue_group は config/system.csv で一元管理されるため、list.csv には含めません。ジョブを無効化するには enable=no を設定します（# コメントアウトは使用しません）。

config/system.csv との責務分担

Benchkit では、実行条件とシステム運用設定を明確に分けます。

  • programs/<code>/list.csv
    • そのアプリをどのシステム・どのノード数・どのMPI/OpenMP条件で流すか
    • アプリごとに変わる条件を書く
  • config/system.csv
    • mode、Runner tag、queue、queue_group など、そのシステムで共通な運用設定を書く
    • 全アプリで共有される条件を書く
  • config/system_info.csv
    • Result Server や /systems に出すシステム表示情報を書く
    • アプリ開発者が、その system が portal 上でどう見えるかを確認するときの正本になる

新しい system を list.csv に追加する前に、config/system.csv と config/system_info.csv の両方に対象 system があるかを確認しておくと、実行条件と portal 表示のずれを減らせる。

この分担により、同じシステムに対して各アプリが mode や queue_group を重複定義する必要がなくなります。

source_info の現時点の方針

Benchkit では、まず top-level application の source provenance を追えることを優先します。 具体的には、Git 管理のアプリであれば repo_url、branch、commit_hash を source_info として入れられる形が望ましいです。 branch は表示用の ref 名であり、branch だけでなく tag 名が入る場合もあります。 新しい result では、追加で ref_name、ref_kind、resolved_commit も記録します。 通常のアプリ build は、対象 repo の対象 ref の最新 commit を使います。 再現実行や監査で commit を固定したい場合だけ、bk_fetch_source の第4引数に expected commit を渡して、意図した commit を build してください。 tar archive を使う場合も、必要に応じて第4引数に expected SHA-256 を渡せます。

一方で、ローカルファイルや依存ライブラリを含む完全な provenance を、現時点ですべての app に必須化する方針ではありません。 portal の /results/usage では、この source provenance が各 app / system の最新 result に対して current-state として見えるので、まずは top-level source tracked を目標に整備すると自然です。

入力ファイルが app repository 内に既にあり、そのまま使う場合は、source_info.resolved_commit が app source と repo 内 input の固定点になります。 この場合、別 manifest や input digest を必須にする必要はありません。 入力metadataは optional な推奨機能です。 無い result も正常に扱われますが、Portal や review で dataset 名を見せたい場合だけ、任意の入力metadataで repo-relative path を補足できます。

bk_record_input \
  --dataset-id myapp-case0 \
  --path benchmarks/case0/input.dat

入力が別の Git repository にあり、app が clone / ref 解決を行っている場合は、URL・ref・resolved commit・repo-relative path だけを bk_record_input へ渡せます。 --repo-url は入力sourceの記録であり、それだけでは public reuse packet の公開条件にはなりません。 public reuse packet へ含めるには、共通層が生成する public_access_check metadata が必要です。 現在は github.com と gitlab.com の repository URL を共通層が匿名 provider API で確認します。 app 側で public_access_check を書く必要はありません。 書かれていても Result JSON 生成時に破棄され、共通層の確認結果だけが採用されます。

input_source_commit=$(git -C "${INPUT_REPO_DIR}" rev-parse HEAD)
bk_record_input \
  --dataset-id myapp-input-case0 \
  --repo-url "$INPUT_REPO_URL" \
  --ref "$INPUT_BRANCH" \
  --commit "$input_source_commit" \
  --path benchmarks/case0

pre-staged input と site-local 情報の扱い

大きな入力データ、restart、学習済みモデル、商用・共同研究由来のデータなどは、repository に直接入れず、site 側の shared filesystem や object storage に置いて参照することがあります。 この場合は、BK_<APP>_INPUT_DIR、BK_<APP>_RESTART_DIR、BK_<APP>_DATASET のような app-local override を用意し、programs/<code>/README.md に期待する directory layout、生成手順、dataset identity を書いてください。

site-local path や allocation / project ID は、それ自体を一律に secret として扱う必要はありません。 公開課題の ID や、実行に必要な shared path を repository に書かざるを得ない場合があります。 ただし、public repository に書く情報は benchmark の理解・実行・検証に必要な最小限にしてください。

  • 必須でない user home path、個人名に強く結びつく path、site-private な運用ログ、private URL、token、password、credential は書かない
  • project / allocation ID は secret ではないが、budget や site 運用に結びつく metadata として扱い、可能なら Portal profile、runner variable、または site-local operations note に置く
  • path そのものではなく、dataset ID、生成 recipe / revision、manifest、SHA-256 や tree digest で「何を読んだか」を識別できるようにする
  • repository の default path は最小限の fallback とし、実運用で site ごとに変わる値は環境変数 override で差し替えられるようにする
  • Result provenance に残すべき情報は、local path より dataset identity と manifest digest を優先する

pre-staged input を使う app では、「正しい場所にファイルがある」だけでは再現性の説明として不足します。 可能であれば input directory と同じ場所に manifest を置き、run 前に manifest / digest を検証して、Result metadata へ dataset identity を残してください。 ただし、これは app 実装の必須条件ではありません。 入力の素性が分かっていて、後から結果を再利用・レビューしやすくしたい場合に追加する補助記録です。

app から実行時の入力metadataを渡す場合は、scripts/bk_functions.sh を source して bk_record_input を使ってください。 bk_record_input は渡された引数から入力metadataを組み立てます。 app 側は schema_version や inputs 配列の形を組み立てず、分かっている事実だけを渡します。 例えば --repo-url、--path、--parameter、--command は同時に渡せます。

最小例:

bk_record_input \
  --dataset-id myapp-case0 \
  --version 2026-09 \
  --type file \
  --recipe "how the benchmark input was prepared"

入力が実ファイルではなく実行引数だけで表せる場合は、--command と -- 以降の引数を渡します。 この場合も共通層で input_info schema を組み立てるため、app 側で JSON を直書きする必要はありません。

case0_args=(32 6 4 3 1 1 1 1 -1 -1 6 50)
bk_record_input \
  --dataset-id myapp-case0-parameters \
  --parameter-set-id CASE0 \
  --result-exp CASE0 \
  --command ./main \
  -- "${case0_args[@]}"

入力が repository と実行時 parameter の両方を持つ場合も、1つの record として書けます。

bk_record_input \
  --dataset-id myapp-case0-input \
  --repo-url https://example.org/myapp-inputs.git \
  --ref main \
  --commit 0123456789abcdef0123456789abcdef01234567 \
  --path cases/case0 \
  --parameter mesh small \
  --command ./run_case \
  -- --case CASE0

Verified へ進める場合は、manifest file だけの hash ではなく、manifest の中で dataset ID、version/revision、生成 recipe、期待 file list、size/hash などを説明できるようにしておくと後から追跡しやすくなります。 digest や source URL などの field が必要になった場合は、app 側に Result JSON schema を直書きさせるより、共通helperまたは共通の受け渡し形式を拡張します。 公開 surface では detailed local path を出さず、dataset identity と検証状態を優先して見せる前提で設計してください。

Portal の /results/usage では、通常の benchmark result に対する入力出自の状態を Input Status として表示します。 この値は estimation 専用ではなく、Result JSON の input_info を見た current-state summary です。

  • None: input_info がない
  • Declared: input_info はあるが、digest 検証や source commit coverage までは示していない
  • Covered: repo-local input または public input source が記録済み source commit で固定されることを示している
  • Verified: manifest / content digest などの証跡と verification_status: "verified" がある

None や Declared はただちに CI failure ではありません。 ただし、長期運用や多拠点再現に使う入力では、可能なら Covered または Verified に近づけてください。

build environment snapshot の方針

CI の共通 wrapper は、build.sh 実行前に runner 側の軽量 snapshot を記録します。 一方で、多くの app は build.sh 内で module load や compiler 設定を行うため、実際の build 環境は app build の直前で記録する必要があります。

CI の build job では scripts/build_tool_wrappers/ を PATH の先頭に入れ、make / cmake / ninja の同名 wrapper が results/environment_snapshot_build_actual.json を更新してから本物の command に委譲します。 そのため、app の build.sh では通常どおり make / cmake / ninja を呼べば十分です。 特殊な独自ビルド command でこれらを経由しない場合は、その command 用の wrapper を共通層に追加してから使ってください。 この snapshot には、主要 compiler / MPI / CUDA / profiler / container command の path と version、loaded modules、allowlist された build 環境変数が含まれます。 TOKEN、SECRET、PASSWORD、AUTH、KEY、CERT などを名前に含む環境変数は値を redacted として記録します。

この actual build snapshot は、将来の build cache key や、同じ source から異なる binary が生じた場合の原因確認に使う前提の記録です。

run placement / node status snapshot の方針

CI の共通 job は、benchmark 本体の run_start より前に results/node_status_snapshot_run.json を記録します。 app の run.sh からこの snapshot 用 helper を呼ぶ必要はありません。

この snapshot は scheduler-neutral な診断情報で、scheduler kind、scheduler が示す node list、観測できた host 数、CPU 数、memory、load average、GPU の軽量状態、run 前に見える GPU compute process の件数と memory 合計を記録します。 process ID、process name、user name は記録しません。 SLURM では可能なら allocation 内の各 node で軽い worker を動かします。 PBS / PJM / unknown scheduler では、取れる範囲の nodefile / environment / local host 情報だけを partial または unsupported として残します。

Result JSON には hash、summary、Measurement Artifact への参照だけを入れ、詳細な node list や GPU 状態は results/node_status_snapshot_run.json 側に残します。 Portal の public surface ではこの Measurement Artifact は表示しません。

build cache の方針

cross build job と native build_run job の build phase では、共通 wrapper scripts/build_with_cache.sh が build.sh の前後で build artifact cache を扱います。 app の build.sh から cache 用の関数を呼ぶ必要はありません。 BK_BUILD_CACHE_DIR が設定されていればそれを cache root として使います。未設定の場合、custom runner が CUSTOM_DIR を渡していれば $CUSTOM_DIR/build_cache/$CUSTOM_RUNNER_PROJECT_SLUG を使います。どちらもなければ build cache は無効です。 cache miss の場合は通常どおり build.sh が実行され、artifacts/、results/source_info.env、results/environment_snapshot_build_actual.json が cache に保存されます。 cache hit の場合は保存済みの artifacts/ と build provenance が復元され、build.sh は実行されません。

cache hit は、少なくとも現在の app build input hash と source provenance が一致するときだけ許可されます。 app 側の build recipe は programs/<code>/build.sh と、任意のpatch file置き場である programs/<code>/patches/ として扱います。 build に必要な app 固有処理は build.sh に閉じ、repo内patchは programs/<code>/patches/ に置いてください。run.sh、profile.sh、estimate.sh、README などは build cache input ではありません。 そのため、profile.sh と estimate.sh では build option の選択や app artifact の再buildを行わないでください。 Git source では cache 内の repo_url / ref_name / resolved_commit に対し、現在の ref commit を git ls-remote で再解決します。 新 metadata がない既存 cache entry は miss になり、通常の build 後に新しい cache として保存されます。 file/archive source では SHA-256 を再計算します。 container image SHA-256 が source_info に入っている場合は container image も再検証します。 container ではない host build でも、common の make / cmake / ninja wrapper を通る場合は build tool 実行直前の build environment fingerprint で照合します。 この fingerprint には loaded modules、選択された build 環境変数、tool の real path、version、binary SHA-256 hash が含まれます。 app 側で cache API を呼ぶ必要はありません。通常どおり module load して make / cmake / ninja を呼ぶだけで、common wrapper が fingerprint を記録します。 Result JSON の build_cache には、cache status、cached binaryの作成時刻、digest、hit/store根拠、miss時の拒否理由が入ります。 cache directory path は入りません。

4. ビルドスクリプトの作成

build.sh の基本構造

#!/bin/bash
set -e
system="$1"
mkdir -p artifacts

source scripts/bk_functions.sh

# ソースコード取得と source_info 生成
REPO_DIR="your-app"
SOURCE_COMMIT="${YOUR_APP_SOURCE_COMMIT:-}"
bk_fetch_source "https://github.com/your-org/your-app.git" "${REPO_DIR}" "main" "${SOURCE_COMMIT}"
cd "${REPO_DIR}"

# システム別ビルド設定
case "$system" in
    Fugaku)
        # A64FX向けクロスコンパイル
        make -j 8 compiler=fujitsu_cross mpi=1
        ;;
    FugakuCN)
        # A64FX向けネイティブコンパイル
        make -j 8 compiler=fujitsu_native mpi=1
        ;;
    MiyabiG)
        # Neoverse-N1向けビルド
        make -j 8 compiler=openmpi-gnu arch=skylake mpi=1
        ;;
    MiyabiC)
        # Intel向けビルド
        make -j 8 compiler=intel arch=skylake mpi=1
        ;;
    RC_GENOA)
        # AMD Genoa向けビルド
        module load system/genoa mpi/openmpi-x86_64
        make -j 8 compiler=openmpi-gnu arch=skylake mpi=1
        ;;
    RC_DGXSP)
        # DGX Spark向けビルド
        source /etc/profile.d/modules.sh
        module load system/ng-dgx nvhpc-hpcx/26.3
        make -j 8 compiler=openmpi-gnu arch=skylake mpi=1
        ;;
    RC_FX700)
        # A64FX系FX700向けビルド
        module load system/fx700 FJSVstclanga
        make -j 8 compiler=fujitsu_native mpi=1 SYSLIBS=
        ;;
    *)
        echo "Unknown system: $system"
        exit 1
        ;;
esac

# 実行ファイルをartifactsに保存
cp your-app_main_executable ../artifacts/

qwsの実際の例

# Fugaku向けA64FXクロスコンパイル
make -j 8 fugaku_benchmark= omp=1 compiler=fujitsu_cross rdma= mpi=1 powerapi=

# MiyabiG向けNeoverse-N1ビルド
make -j 8 fugaku_benchmark= omp=1 compiler=openmpi-gnu arch=skylake rdma= mpi=1 powerapi=

# FX700向けA64FXネイティブビルド
make -j 8 fugaku_benchmark= omp=1 compiler=fujitsu_native rdma= mpi=1 powerapi= SYSLIBS=

ビルドテスト

# A64FX向けビルド（Fugaku環境）
bash programs/<code>/build.sh Fugaku
ls artifacts/  # クロスコンパイル済み実行ファイルを確認

Artifacts最適化の注意点

CI/CDパイプラインでのartifacts保存を最適化するため、以下の点に注意してください：

推奨事項：

  • 必要な実行ファイルのみを保存
  • ソースコード全体やビルドディレクトリ全体の保存は避ける
  • 適切なディレクトリ構造で整理

例（qwsの場合）：

# 良い例：必要なファイルのみ保存
mkdir -p artifacts
cp qws/qws_main_executable artifacts/

# 避けるべき例：ディレクトリ全体の保存
# cp -r qws/ artifacts/  # ソースコード全体は避ける

効果：

  • CI/CDパイプラインの実行時間短縮
  • ストレージ使用量の削減
  • アーティファクトのアップロード/ダウンロード時間の短縮

5. 実行スクリプトの作成

run.sh の基本構造

#!/bin/bash
set -e
system="$1"
nodes="$2"
numproc_node="$3"
nthreads="$4"
export OMP_NUM_THREADS=$nthreads

source "${PWD}/scripts/bk_functions.sh"

mkdir -p results && > results/result

# 実行時にも入力データやソース checkout が必要な場合は bk_fetch_source を使う。
# build artifacts の実行ファイルだけで足りる場合、run.sh で再 clone する必要はない。
REPO_DIR="your-app"
bk_fetch_source "https://github.com/your-org/your-app.git" "${REPO_DIR}" "main"

# artifactsから実行ファイルをコピー
cp artifacts/your-app_main_executable "${REPO_DIR}/"

cd "${REPO_DIR}"

case "$system" in
    Fugaku|FugakuCN)
        # MPI実行（富岳）
        mpiexec -n $((nodes * numproc_node)) ./main [args] > output
        # 結果解析
        FOM=$(grep "performance" output | awk '{print $2}')
        bk_emit_result --fom "$FOM" --fom-unit s --fom-version v1.0 --exp test \
            --nodes "$nodes" --numproc-node "$numproc_node" --nthreads "$nthreads" >> ../results/result
        ;;
    MiyabiG|MiyabiC)
        # MPI実行（Miyabi）
        mpirun -n $((nodes * numproc_node)) ./main [args] > output
        FOM=$(grep "performance" output | awk '{print $2}')
        bk_emit_result --fom "$FOM" --fom-unit s --fom-version v1.0 --exp test \
            --nodes "$nodes" --numproc-node "$numproc_node" --nthreads "$nthreads" >> ../results/result
        ;;
    *)
        echo "Unknown system: $system"
        exit 1
        ;;
esac

# NFS同期
cd ..
sync

結果フォーマット

results/result の各行は以下の形式：

FOM:5.752 FOM_unit:s FOM_version:DDSolverJacobi Exp:CASE0 node_count:1 numproc_node:4 nthreads:12
SECTION:compute_kernel time:0.30
SECTION:communication time:0.20
OVERLAP:compute_kernel,communication time:0.05

bk_functions.sh の利用（推奨）：

scripts/bk_functions.sh を source して、標準化された出力関数を使用してください：

source "${PWD}/scripts/bk_functions.sh"

# FOM出力
bk_emit_result --fom 5.752 --fom-unit s --fom-version DDSolverJacobi --exp CASE0 \
    --nodes 1 --numproc-node 4 --nthreads 12 >> results/result

# FOM内訳（オプション）
bk_emit_section compute_kernel 0.30 >> results/result
bk_emit_section communication 0.20 >> results/result
bk_emit_overlap compute_kernel,communication 0.05 >> results/result

bk_emit_result の引数：

  • --fom 数値 - 性能指標（必須）
  • --fom-unit 文字列 - FOM の単位（推奨。例: s, GB/s, GFLOPS, token/s）
  • --fom-version 文字列 - バージョン情報
  • --exp 文字列 - 実験名
  • --nodes 数値 - ノード数
  • --numproc-node 数値 - ノードあたりプロセス数
  • --nthreads 数値 - プロセスあたりスレッド数
  • --confidential 文字列 - 機密データ（チーム限定表示）

省略された引数は出力に含まれません。--fom のみが必須ですが、FOM の意味を誤読しないよう --fom-unit も原則として指定してください。

最低限必要な出力

新しい app を Benchkit に接続する最低ラインは、run.sh が results/result に少なくとも FOM:<数値> 相当の結果を書けることです。 ただし FOM には単位が含まれないため、FOM_unit:s のように単位も出してください。 多くのアプリでは経過時間の s で十分ですが、システムソフトウェアやライブラリでは GB/s、GFLOPS、token/s などになることがあります。 bk_emit_result --fom ... --fom-unit ... を使うと、FOM、単位、実験名、ノード数、プロセス数、スレッド数を同じ形式で出力できます。

source_info は必須ではありませんが、Git などから source を取得する app では bk_fetch_source を使って results/source_info.env を残すことを推奨します。 section / overlap / profiler archive は、詳細分析や推定を使う場合の任意拡張です。

Measurement Artifacts（任意）

詳細データがある場合、profiler archive は従来通り results/padata[0-9].tgz として保存できます：

# PAデータの作成例
mkdir -p pa
echo "detailed_data" > pa/analysis.dat
tar -czf ../results/padata0.tgz ./pa

Fugaku で fapp を使う場合

Fugaku 系アプリでは、アプリ側が profiler tool を内部で選び、Benchkit 共通の bk_profiler helper に渡す形が扱いやすいです。 bk_profiler は profiler ごとの raw data / postprocess report をまとめて results/padata*.tgz に保存し、archive 内の bk_profiler_artifact/meta.json に metadata を入れます。Benchkit や推定 package はこの meta.json を見て、tool、level、report kind を機械的に判断できます。

アプリが独自の詳細 timer table を持つ場合は、まず小さな results/*.json として保存し、bk_record_timing_observation で登録してください。この JSON は Result 送信時に Measurement Artifacts として保存されます。timing_observations は未レビューの観測値を残すための任意機能であり、SECTION: / OVERLAP: や fom_breakdown へ昇格するには、timer ID、inclusive / exclusive の扱い、overlap window の意味を別途レビューします。

fapp では共通 level として次を扱います。

  • single → pa1
  • simple → pa1..pa5
  • standard → pa1..pa11
  • detailed → pa1..pa17

single は既定で text summary、simple/standard/detailed は既定で text + CSV report を保存します。CSV は fapp 固有の report として扱い、ほかの profiler が同じ形式を持つ必要はありません。

# qws は Fugaku 系 build / run の内部で fapp + detailed を利用
bash programs/qws/build.sh Fugaku
bash programs/qws/run.sh Fugaku 1 4 12

追加オプションが必要なら、以下を併用できます。

  • BK_PROFILER_LEVEL
    • single|simple|standard|detailed を上書き
  • BK_PROFILER_REPORT_FORMAT
    • text|csv|both を上書き
  • BK_PROFILER_ARGS
    • fapp -C にそのまま渡す追加引数
  • BK_PROFILER_REPORT_ARGS
    • fapp -A / fapppx -A にそのまま渡す追加引数
  • BK_PROFILER_DIR
    • raw profile data の出力先ディレクトリ名（既定値: pa）

archive の中身は概ね次の形になります。

bk_profiler_artifact/
  meta.json
  raw/
    rep1/
    ...
    rep17/
  reports/
    fapp_A_rep1.txt
    cpu_pa_rep1.csv

より一般的な profiler helper の設計方針は Profiler Support Guide を参照してください。 level の早見表と portal 上の見え方は Profiler Level Reference にまとめています。

GPU アプリで ncu を使う場合

NVIDIA GPU 向けアプリでは、Nsight Compute CLI (ncu) を bk_profiler 経由で使えます。 MPI launcher 経由のアプリでは、bk_profiler ncu が既定で --target-processes all を付け、child process の CUDA kernel も採取対象にします。 MiyabiG と RC_GH200 のように計算ノード構成が同じ Grace-Hopper GPU 系の場合は、ジョブ投入方式だけを system 設定に任せ、アプリ側の build/run と profiler 採取は共通化するのが自然です。

BK_PROFILER_ARGS="--set full --kernel-name regex:your_kernel" \
bk_profiler ncu --level single --archive ../results/padata0.tgz --raw-dir ncu -- \
    mpirun -np 1 ./your_gpu_app input.inp

ncu の既定 level は single です。最初は採取時間を抑えるため、single または simple から始めてください。 padata*.tgz には、可能な場合は bk_profiler_artifact/reports/ncu_import_rep1.txt に text report、BK_PROFILER_NCU_RAW_CSV=true の場合は bk_profiler_artifact/raw/rep1/profile_raw.csv に raw CSV が保存されます。 Nsight Compute の binary report (*.ncu-rep など) は重いため既定では padata*.tgz から除外されます。デバッグ目的で保存したい場合だけ BK_PROFILER_ARCHIVE_NCU_REPORT=true を明示してください。 site の既定 module に ncu が含まれない場合は、アプリ側で module を load するか、system 固有の module 変数を用意してください。 app 固有の GPU kernel window、短縮 input、module override、profiler override を持つ場合、その既定は共通 CI/matrix ではなく app wrapper 側に置きます。 具体的な設定例は programs/<code>/ 配下の app-local documentation に置きます。GENESIS の現在の例は programs/genesis/README.md を参照してください。 完全に手動指定したい場合は app wrapper の規約に加えて BK_PROFILER_ARGS を使えます。

6. ローカルテスト

手元環境でのスクリプト確認

# ビルドテスト（対象 system は実際に使う設定に合わせる）
bash programs/<code>/build.sh Fugaku
ls artifacts/

# 実行テスト
bash programs/<code>/run.sh Fugaku 1 4 12
cat results/result  # FOM:値が含まれることを確認
ls results/         # 必要に応じてpadata*.tgzも確認

結果の確認ポイント

  • artifacts/ に実行ファイルが生成される
  • results/result に FOM: を含む行が出力される
  • エラーなく完了する

7. バッチジョブテスト

test_submit.sh の使用方法

# list.csvの内容確認
cat programs/<code>/list.csv

# 1行目の設定でテスト実行
bash scripts/test_submit.sh <code> 1

# Fugakuでdefault group以外を使う場合
BK_ALLOCATION_PROJECT_ID=ra000009 bash scripts/test_submit.sh <code> 1

test_submit.sh の機能

  • 引数検証: プログラム名と行番号の妥当性チェック
  • 設定表示: 選択された実行条件の詳細表示
  • 自動投入: システムに応じたバッチジョブ投入

実行例

$ bash scripts/test_submit.sh qws 1
Selected configuration from programs/qws/list.csv (line 1):
  Fugaku,yes,1,4,12,0:10:00

Parsed values:
  system=Fugaku, enable=yes, mode=cross (from system.csv), queue_group=small (from system.csv)
  nodes=1, numproc_node=4, nthreads=12, elapse=0:10:00

pjsub -L rscunit=rscunit_ft01,rscgrp=small,node=1,elapse=0:10:00 ...

エラー対処

# 行番号が範囲外の場合
$ bash scripts/test_submit.sh qws 10
Error: Line 10 does not exist in programs/qws/list.csv
Available lines: 1 to 2

Contents of programs/qws/list.csv:
Line# | Configuration
------|-------------
  H   | system,enable,nodes,numproc_node,nthreads,elapse
    1 | Fugaku,yes,1,4,12,0:10:00

対応システム

  • Fugaku/FugakuCN: PJM（富岳）
  • MiyabiG/MiyabiC: PBS（Miyabi）
  • RC_GH200/RC_DGXSP/RC_GENOA/RC_FX700: SLURM（クラウド）

注意: トークンを消費するプロジェクトでは、groupsの第二要素が自動で選択されます。変更したい場合はscripts/test_submit.shを編集してください。

8. PR作成

コミット・プッシュ

# 変更をステージング
git add programs/<code>/

# コミット
git commit -m "Add new app <code>

- Implement build.sh for multiple systems
- Add run.sh with proper FOM output
- Configure list.csv for target systems
- Test completed on Fugaku"

# プッシュ
git push origin add-<code>

GitHub pull request では、通常は result server test や shellcheck などの軽量な check だけを実行します。 HPC 上の benchmark CI が必要な場合は、maintainer が GitLab Manual CI を起動し、code と system の workflow input で対象 app / system を明示してください。 [code:<code>] や [system:<system>] の commit message tag は、GitLab 側の legacy scope control として残っていますが、新しいPR運用では使わないでください。

PR作成時の記載内容

タイトル: Add new application: <code>

説明:

## 新しいアプリケーション: <code>

### 概要
- アプリケーション名: <code>
- ソースコード: https://github.com/your-org/your-app
- 性能指標: [FOMの説明]

### テスト済み環境
- [x] Fugaku (バッチジョブ)
- [ ] MiyabiG
- [ ] MiyabiC

### 入力データ（該当する場合）
- 種類: inputなし / repo-local / public archive / site-local override / other
- 説明: [dataset名、取得元、環境変数名、manifest/digestなど、書ける範囲で]

### 確認事項
- [x] build.sh が正常に動作
- [x] run.sh が FOM を出力
- [x] test_submit.sh でバッチジョブ投入成功
- [x] 結果フォーマットが正しい

レビューポイント

  • システム別ビルド設定の妥当性
  • 結果フォーマットの正確性
  • 入力データがある場合、その出所説明が分かりやすいか、Input Status が None / Declared / Covered / Verified のどれに相当するか
  • エラーハンドリングの適切性
  • ドキュメントの更新

注意事項

CI/CD環境

  • 各パイプラインは独立したディレクトリで実行
  • artifacts/ と results/ は自動的に管理される
  • ビルド・実行ファイルの衝突は基本的に発生しない

Git リポジトリの取り扱い

  • ソース取得は原則 scripts/bk_functions.sh の bk_fetch_source <source> <dest_dir> [branch_or_tag] [expected_commit_or_sha256] を使う
  • bk_fetch_source は Git URL または tar archive を取得・展開し、results/source_info.env に source provenance を書く
  • Git source では expected commit を指定すると、その commit に checkout して一致しなければ失敗する
  • tar archive では expected SHA-256 を指定すると、一致しなければ失敗し、source_info に sha256sum も記録する
  • build.sh と run.sh の両方で同じ checkout が必要な場合も、直接 git clone せず bk_fetch_source に寄せる
  • run.sh が build artifact の実行ファイルだけで完結する場合は、実行時に再 clone しない
  • 取得元 URL を site ごとに変えたい場合は、app 固有環境変数で上書きできる形にしてもよい
  • 非公開の URL、proxy host、token などは OSS repo に直書きしない