Skip to content

add-app.md

Latest commit

 

History

History
709 lines (562 loc) · 33 KB

add-app.md

File metadata and controls

709 lines (562 loc) · 33 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 が生じた場合の原因確認に使う前提の記録です。

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 は、詳細分析や推定を使う場合の任意拡張です。

Performance Analysis データ（任意）

詳細データがある場合は 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 を機械的に判断できます。

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 に直書きしない