Skip to content

Latest commit

 

History

History
390 lines (311 loc) · 15.6 KB

ADD_APP.md

File metadata and controls

390 lines (311 loc) · 15.6 KB

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

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

目次

  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,mode,queue_group,nodes,numproc_node,nthreads,elapse
# Fugaku での複数設定例
Fugaku,cross,small,1,4,12,0:10:00
Fugaku,cross,small,2,4,12,0:20:00
# MiyabiG/MiyabiC での設定例
MiyabiG,cross,debug-g,1,1,72,0:10:00
MiyabiC,cross,debug-c,1,1,112,0:10:00
# ログインノードでのテスト用
FugakuLN,native,small,1,1,1,0:10:00

パラメータ説明：

  • system: 実行システム名（system.csvと対応）
  • mode: cross（ビルド→実行分離）または native（同時実行）
  • queue_group: キューグループ名
  • nodes: ノード数
  • numproc_node: ノードあたりプロセス数
  • nthreads: スレッド数
  • elapse: 実行時間制限

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

build.sh の基本構造

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

# ソースコード取得
git clone https://github.com/your-org/your-app.git
cd your-app

# システム別ビルド設定
case "$system" in
    Fugaku)
        # A64FX向けクロスコンパイル
        make -j 8 compiler=fujitsu_cross mpi=1
        ;;
    FugakuCN)
        # A64FX向けネイティブコンパイル
        make -j 8 compiler=fujitsu_native mpi=1
        ;;
    FugakuLN)
        # x86_64向けビルド（テスト用）
        make -j 2 compiler=gnu arch=skylake mpi=
        ;;
    MiyabiG)
        # Neoverse-N1向けビルド
        make -j 8 compiler=openmpi-gnu arch=skylake mpi=1
        ;;
    MiyabiC)
        # Intel向けビルド
        make -j 8 compiler=intel arch=skylake mpi=1
        ;;
    *)
        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=

ビルドテスト

# ログインノードでのビルドテスト
bash programs/<code>/build.sh FugakuLN
ls artifacts/  # 実行ファイルが生成されることを確認

# 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"

mkdir -p results && > results/result

# ソースコード取得（既存ならスキップ）
[[ -d your-app ]] || git clone https://github.com/your-org/your-app.git

# artifactsから実行ファイルをコピー
cp artifacts/qws_main_executable your-app/

cd your-app

case "$system" in
    Fugaku|FugakuCN)
        # MPI実行（富岳）
        mpiexec -n $((nodes * numproc_node)) ./main [args] > output
        # 結果解析
        FOM=$(grep "performance" output | awk '{print $2}')
        echo "FOM:$FOM FOM_version:v1.0 Exp:test node_count:$nodes" >> ../results/result
        ;;
    FugakuLN)
        # ログインノードでのテスト実行
        export OMP_NUM_THREADS=12
        ./main [args] > output
        FOM=$(grep "performance" output | awk '{print $2}')
        echo "FOM:$FOM FOM_version:v1.0 Exp:test node_count:$nodes" >> ../results/result
        ;;
    MiyabiG|MiyabiC)
        # MPI実行（Miyabi）
        mpirun -n $((nodes * numproc_node)) ./main [args] > output
        FOM=$(grep "performance" output | awk '{print $2}')
        echo "FOM:$FOM FOM_version:v1.0 Exp:test node_count:$nodes" >> ../results/result
        ;;
    *)
        echo "Unknown system: $system"
        exit 1
        ;;
esac

# NFS同期
cd ..
sync

結果フォーマット

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

FOM:5.752 FOM_version:DDSolverJacobi Exp:CASE0 node_count:1

必須フィールド：

  • FOM:数値 - 性能指標（必須）
  • FOM_version:文字列 - バージョン情報
  • Exp:文字列 - 実験名
  • node_count:数値 - ノード数

オプション：

  • confidential:TeamA - 機密データ（チーム限定表示）

Performance Analysis データ

詳細データは results/padata[0-9].tgz として保存：

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

6. ローカルテスト

ログインノードでのテスト

# ビルドテスト
bash programs/<code>/build.sh FugakuLN
ls artifacts/

# 実行テスト
bash programs/<code>/run.sh FugakuLN 1
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

test_submit.sh の機能

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

実行例

$ bash scripts/test_submit.sh qws 1
Selected configuration from programs/qws/list.csv (line 1):
  MiyabiG,cross,debug-g,1,1,72,0:10:00

Parsed values:
  system=MiyabiG, mode=cross, queue_group=debug-g
  nodes=1, numproc_node=1, nthreads=72, elapse=0:10:00

qsub -q debug-g -l select=1:ompthreads=72 -l walltime=0:10:00 -W group_list=gq49 script.sh
1258470.opbs

エラー対処

# 行番号が範囲外の場合
$ 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,mode,queue_group,nodes,numproc_node,nthreads,elapse
    1 | MiyabiG,cross,debug-g,1,1,72,0:10:00
    2 | MiyabiC,cross,debug-c,1,1,112,0:10:00

対応システム

  • Fugaku/FugakuCN: PJM（富岳）
  • MiyabiG/MiyabiC: PBS（Miyabi）
  • RC_GH200: SLURM（クラウド）
  • FugakuLN: テスト専用（投入なし）

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

8. PR作成

コミット・プッシュ

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

# コミット（[code:<code>]で追加したアプリのみテスト実行）
git commit -m "Add new app <code>

[code:<code>]

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

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

注意: [code:<code>]をコミットメッセージに含めることで、CI/CDパイプラインでは追加したアプリのみがテスト実行され、既存の全プログラムのテストは実行されません。これにより実行時間を大幅に短縮できます。

PR作成時の記載内容

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

説明:

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

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

### テスト済み環境
- [x] FugakuLN (ログインノード)
- [x] Fugaku (バッチジョブ)
- [ ] MiyabiG
- [ ] MiyabiC

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

レビューポイント

  • システム別ビルド設定の妥当性
  • 結果フォーマットの正確性
  • エラーハンドリングの適切性
  • ドキュメントの更新

注意事項

CI/CD環境

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

Git リポジトリの取り扱い

  • build.sh と run.sh 両方でcloneする場合、ディレクトリ衝突に注意
  • 既存チェック: [[ -d repo ]] || git clone ...