Skip to content
BranchesTags

Repository files navigation

Experiment Management System

SlurmおよびPBS (qsub/Miyabi) ベースの実験管理システムです。自動でスケジューラを判別し、実験の作成・投入・通知・再開をコマンド一つで行えます。

💡 基本コンセプト

本システムは、主に以下の2点によって動作します。

  1. シェル環境の拡張: 便利な実験管理コマンド（runx, cdx, lsx, cancelx など）を自身のシェル環境に読み込み、実験の移動や実行を簡単に行えるようにします。
  2. 実験テンプレートの自動適用 (templates/ のコピー): make create_exp コマンドを使用して、事前に定義された実験テンプレート（コード、設定ファイル、ジョブスクリプト）を実験ディレクトリごとに展開し、実験の独立した開発・追跡を可能にします。

セットアップ

1. 初期セットアップ

make setup

2. Python環境の同期

make uv_sync p=<partition>

Note

make uv_sync および make jupyter コマンドは現在 Slurm 環境のみのサポートとなっています。PBS (qsub) 環境での Python 環境同期や Jupyter 起動については、今後のアップデートをお待ちいただくか、手動で実行してください。

3. シェルヘルパーの設定

ジョブ管理用コマンド（runx, cdx, lsx, cancelx など）を自身のシェル環境で使えるようにするため、~/.bashrc から本レポジトリの shell/template-daily.sh を source します。テンプレート側は関数定義だけで、Git のグローバル設定変更や jq 未導入時のシェル終了は行いません。

リポジトリのルートで一度だけ実行してください。すでに同じ設定があれば追記しません。

repo_root="$(git rev-parse --show-toplevel)"
loader_line="source \"${repo_root}/shell/template-daily.sh\""
grep -Fqx "${loader_line}" ~/.bashrc || printf '\n%s\n' "${loader_line}" >> ~/.bashrc
source ~/.bashrc

4. Slack通知の設定（任意）

~/.bashrc に以下を設定します。

export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."

ディレクトリ構成

.
├── experiments/          # 実験ごとの設定・コード
│   └── 0001_20260101_baseline/
│       ├── run_slurm.sh  # リソース設定・実行コマンド
│       ├── experiment.py
│       └── config.yml
├── outputs/              # Pythonスクリプトの出力先
│   └── 0001_20260101_baseline/
├── logs/                 # Slurmログ・メタデータ
│   └── 0001_20260101_baseline/
│       └── 1234/         # job_id
│           ├── slurm.out
│           ├── run_metadata.yaml
│           ├── bootstrap_failure.log  # 初期化失敗時のみ
│           └── command.sh
├── lib/                  # 共通ライブラリコード
├── templates/            # 実験作成時のテンプレートファイル
├── scripts/              # ジョブ実行・監視用の内部スクリプト
│   ├── slurm_entry.sh
│   └── notify_slack.sh
└── tools/                # 各種管理ツールの実体スクリプト
    ├── create_exp.sh
    ├── resume_exp.sh
    ├── rename_exp.sh
    ├── mark_failed.sh
    ├── cancel_job.sh
    ├── uv_sync.sh
    ├── start_jupyter.sh
    └── first_setup.sh

主な機能と対応スケジューラ

投入（runx）は Slurm (sbatch) 専用です。 PBS (qsub/Miyabi) 環境では runx は使えません。 一方、ジョブ実行中の状態管理（slurm_entry.sh）とキャンセル（cancelx）は Slurm/PBS 両方に対応しています（PBS環境で既に投入済みのジョブを管理する用途を想定）。

  • パーティション自動判定: make create_exp 実行時に、ジョブの実行時間制限（Time limit）に 応じて適切なパーティション（Slurm: small-{owner} 等）を自動選択し run_slurm.sh に焼き込みます。
  • 依存ジョブ指定: run_slurm.sh 内の #SBATCH --dependency=afterok:<job_id> を 有効化することで指定します。job_idは依存先実験の outputs/{exp}/latest_job_id.txt を参照します。
  • アレイジョブ実行: run_slurm.sh 内でarray/seqモードを有効化することで、探索パラメータに 応じた複数ジョブの一括投入をSlurmのアレイジョブ機能（--array）で実行します。
  • ジョブキャンセル: cancelx <job_id> で自動的に scancel または qdel を呼び出してジョブを停止します（Slurm/PBS両対応）。
  • 終了理由の記録: 初期化失敗は bootstrap_failure.log と run_metadata.yaml の fail_reason に、実行後の終了状態は run_metadata.yaml に記録します。通知失敗は本体ジョブを停止させず、標準エラーに警告として残します。
  • ログ自動管理: ジョブ終了時に標準出力・標準エラーを logs/{exp_name}/{job_id}/ 以下に slurm.out / pbs.err として自動回収します。
  • Slack通知機能: ジョブの開始・終了・失敗（タイムアウトやOOMを含む）を判定し、Slackへ通知します（アレイジョブにも対応）。Webhook・jq・通信の異常は警告のみです。

実験のライフサイクル

1. 実験を作成する

make create_exp name=<exp_name>

experiments/ 以下にディレクトリが作成され、run_slurm.sh / experiment.py / config.yml がテンプレートからコピーされます。

2. run_slurm.sh を編集する

run_slurm.sh は完全な #SBATCH スクリプトです。make create_exp の時点で --partition と time-limit警告用の --signal マージンは自動計算済みなので、 必要ならリソースを直接編集します。

#SBATCH --gres=gpu:1
#SBATCH --cpus-per-task=32
#SBATCH --mem=80g
#SBATCH --time=24:00:00
# ↑ を大きく変える場合は --partition と --signal も手動で合わせて見直す

# 実行コマンド
RUN_COMMAND="python experiments/0001_20260101_baseline/experiment.py --config config.yml"

複数組み合わせを投入したい場合は、同じファイル内の Array run / Seq run セクションを 有効化します（詳細は USAGE.md 参照）。

3. ジョブを投入する

# 最新の実験を投入
runx

# 実験IDを指定して投入
runx 1

# dirty状態で投入
runx --allow-dirty

依存関係を指定したい場合（実験1が終わったら実験2を投入、等）は、実験2の run_slurm.sh にある #SBATCH --dependency=afterok:<job_id> を有効化し、 実験1の outputs/{exp}/latest_job_id.txt の値を書き込んでから runx します。

4. 実験を確認する

# 実験一覧を表示
lsx

# 実験ディレクトリに移動
cdx      # 最新
cdx 1    # ID指定

5. ジョブをキャンセルする

cancelx <job_id>
cancelx <job_id> <reason>

実験ごとに独自のルール・スキルを持たせたい場合

experiments/<id>_.../CLAUDE.md や experiments/<id>_.../.claude/skills/ を置くと、 その実験を触っている間だけ有効な追加ルール・専用スキルとして機能します （Claude Codeがサブディレクトリ単位で自動的にlazy-loadする標準機能で、agent設定側の変更は不要）。 詳細は TEMPLATE_CONCEPT.md を参照。

実験の管理

リネーム

make rename_exp name=<exp_id_or_name> new=<new_name>

失敗マーク

make mark_fail name=<exp_id_or_name> reason=<reason>

ディレクトリ名に _FAILED_<date>_<reason> が付与されます。

再開

# 最新の実験を再開
make resume_exp name=<exp_id_or_name>

# suffixを指定して再開
make resume_exp name=<exp_id_or_name> suffix=retry

元の実験の設定・コードがコピーされ、新しいIDで実験が作成されます。config.yml に再開元の情報が記録されます。

Slack通知

ジョブの状態変化時にSlack通知が届きます。

タイミング 通知
ジョブ開始 🚀 STARTED
正常終了 ✅ FINISHED
失敗 ❌ FAILED
タイムアウト ❌ FAILED (TIMEOUT)
キャンセル・割り込み ⚡ INTERRUPTED

通知のオン・オフは環境変数で制御できます。

export SLACK_NOTIFY_ON_START=1
export SLACK_NOTIFY_ON_FINISH=1
export SLACK_NOTIFY_ON_FAIL=1

ジョブログ

ジョブ終了後、logs/{exp_name}/{job_id}/ に以下が保存されます。

ファイル 内容
slurm.out ジョブの標準出力（Slurm時は標準エラーも含む）
pbs.err PBS (qsub) 時の標準エラー出力
run_metadata.yaml ジョブのメタデータ・最終ステータス
command.sh 実行されたコマンド

run_metadata.yaml のステータス一覧：

RUNNING / COMPLETED / FAILED / TIMEOUT / CANCELLED / OUT_OF_MEMORY / NODE_FAIL

Jupyter

make jupyter p=<partition> mem=<memory>

# 例
make jupyter p=small-david01 mem=32g

更新履歴 (Change Log)

  • 2026-06-19 (qsub対応): PBS (qsub/Miyabi) 環境への対応を追加。スケジューラ自動検知、PBS用ヘッダー・パーティション選択・ログ回収・ジョブキャンセル・依存指定の追加。
  • 2026-06-16 (Slackアレイ通知): Slackへのアレイジョブ通知機能、およびリモート環境からのデータ収集・送信スクリプトを追加。
  • 2026-06-13 (メタデータ分離): 設定ファイル (config.yml) と実行メタデータの分離、および resume/create ツールのアップデート。
  • 2026-06-13 (出力ディレクトリ): 出力ディレクトリ構造の整理とベース設定の追加。

About

ベクトル検索で類似病理パッチを選出する

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages