complexa-slurm

Complexa SLURM スキル

slurm_utils/launch_protein_binder_search.sh、 slurm_utils/launch_laproteina_design_pipeline.sh、 slurm_utils/launch_monomer_eval_from_pdb_dir.sh、および slurm_utils/launch_laproteina_train.sh を使って、Proteina-Complexa のジョブを リモート SLURM クラスターに送信します。まずローカル環境とクラスター環境を調査し、適切なフラグを収集します。必ず --dry-run でプレビューし、送信前に解決済みの sbatch をユーザーに提示してください。その後、ジョブを送信してジョブ ID を取得し、再実行用の slurm_manifest.json を出力します。

complexa CLI は使用しません。 SLURM への送信は bash スクリプトのみで行います。complexa slurm サブコマンドはありません。ランチャーは .env を読み込み、リポジトリを rsync し、sbatch スクリプトを生成して、SSH 経由で sbatch を呼び出します。ssh ... sbatch <<EOF で置き換えようとしないでください。rsync によるゲート、スイーパーの展開、--dry-run による安全策が失われます。

このスキルでできること

• クラスターの GPU で、単一のターゲットまたは --targets-file を使って、4 段階の バインダー検索 パイプライン（生成 → フィルタリング → 評価 → 分析）を実行します。 対応する configs/search_*_pipeline.yaml をランチャーに渡すことで、Complexa の 3 種類の設計パイプライン（タンパク質バインダー（デフォルト）、 リガンドバインダー、AME／酵素の足場設計）を実行します。
• LaProteina モノマー設計（launch_laproteina_design_pipeline.sh、 デフォルト設定 design_monomer_pipeline.yaml）を実行し、条件なしでタンパク質を生成します。
• YAML の設定（nnodes_、ngpus_per_node_、ncpus_per_task_train_、run_name）に基づいて規模を決めた、マルチノードの 分散トレーニング を実行します。
• 送信ごとに --runtime を指定して、Docker（Pyxis/Enroot） と UV venv のランタイムを選択します。
• クラスター全体で Hydra スイープ（--sweeper）と設定ごとのオーバーライド（--override）を実行します。
• デフォルトで安全 — すべての送信は、ユーザーが承認する必要のあるドライランのプレビューを経てから実行されます。
• rsync で結果を自動ダウンロードします（--skip-download でスキップ可能）。

ステップ 1：クラスターの事前チェック

ローカルの事前チェック（_shared/scripts/preflight.sh）では、ローカルホストの GPU／チェックポイント／ツールを確認します。SLURM への送信には、クラスターへの接続性、sbatch バイナリ、および稼働中のパーティションも必要です。両方の事前チェックを実行してください。

bash .claude/skills/_shared/scripts/preflight.sh           # local
bash .claude/skills/complexa-slurm/scripts/cluster_preflight.sh   # cluster

cluster_preflight.sh は cluster_preflight.json を書き出し、次の項目を確認します。

1. .env のセクション 5（CLUSTER_USER、CLUSTER_HOST、CLUSTER_ACCOUNT、 CLUSTER_PARTITION、CLUSTER_ROOT_REMOTE、CLUSTER_DATA_PATH、 CLUSTER_RUNTIME）が設定されていること。ランタイム固有の設定： CLUSTER_CONTAINER_IMAGE（docker）、または CLUSTER_UV_VENV と CLUSTER_CACHE_DIR （uv）。
2. ssh -o BatchMode=yes -o ConnectTimeout=5 $CLUSTER_USER@$CLUSTER_HOST true が成功すること（パスワードなしの SSH がすでに設定されている必要があります）。
3. ログインノードの $PATH に sbatch があること。
4. sinfo -p $CLUSTER_PARTITION -h が 1 つ以上のノードを返すこと。
5. CLUSTER_CKPT_PATH と CLUSTER_SHARED_MODELS_PATH（設定されている場合）がクラスター上に存在すること。
6. ローカルリポジトリの git SHA（マニフェスト用）。

必須項目のチェックに 1 つでも失敗した場合は、ステップ 2 に進まないでください。まず .env、SSH、または権限を修正してください。各変数の意味については reference/cluster_env.md を参照してください。

ステップ 2：ワークロードを選択

目的	起動スクリプト
Complexa 設計パイプライン（タンパク質バインダー、リガンドバインダー、AME）	slurm_utils/launch_protein_binder_search.sh（対応する configs/search_*_pipeline.yaml を渡します）
LaProteina の条件なしモノマー設計	slurm_utils/launch_laproteina_design_pipeline.sh
PDB ディレクトリからのモノマー評価	slurm_utils/launch_monomer_eval_from_pdb_dir.sh
分散トレーニング（ファインチューニング、RL、ベーストレーニング）	slurm_utils/launch_laproteina_train.sh

フラグの全一覧は reference/slurm_workloads.md を参照してください。

ステップ 3：AskUserQuestion でパラメーターを確認する

コンテキストで不足している情報だけを尋ねます。推奨する順序は次のとおりです。

1. ワークロード — binder search／LaProteina monomer design／training。
2. ターゲット／タスク（binder） — 例：22_DerF21、02_PDL1、39_7V11_LIGAND、 または M0096_1chm。バッチモードの場合は --targets-file のパス。
3. Config YAML のパス（training） — デフォルトは configs/training_local_latents.yaml です。別のものを使うか尋ねます。
4. ランタイムの上書き — .env のデフォルトのままにするか、docker／uv を指定しますか？
5. スイープ — --sweeper FILE を渡しますか？（binder のみ）
6. ターゲットファイル — --targets-file FILE と --num-runs N を指定しますか？（binder のみ）
7. すでにクラスター上にいますか？ — ユーザーがログインノードにいる場合は --on-cluster を渡します（SSH／rsync をスキップします）。binder スクリプトのみ。
8. 結果をリモートに残しますか？ — --skip-download を渡すと、出力をクラスター上に残します。デフォルトでは rsync でローカルに戻します。

ステップ 4：必ず最初にドライランを実行する

コマンドを組み立て、--dry-run を付けて実行します。出力全体をユーザーに提示します。 特に、生成された sbatch スクリプトの本文、Hydra のオーバーライド、rsync の転送先、 およびリソースブロック（--nodes、--gres=gpu、--time、 --partition）を提示します。送信前に、明確な「はい」または「いいえ」の回答を得てください。

./slurm_utils/launch_protein_binder_search.sh --dry-run 22_DerF21
./slurm_utils/launch_laproteina_design_pipeline.sh --dry-run
./slurm_utils/launch_laproteina_train.sh --dry-run --config configs/training_local_latents.yaml

ドライランでは、「DRY RUN MODE — No changes will be made」と「Would create slurm_batch_script_*.sh with content: …」がログに出力されます。このブロックはそのまま提示してください。

この確認が必須である理由： 実際にジョブを送信すると、アカウントのクォータが消費され、 多数のノード時間が割り当てられる可能性があり、別のユーザーのジョブが追い出される場合もあります。 また、スクリプトが上書きを拒否する $CLUSTER_ROOT_REMOTE 上に実行ディレクトリが作成されます。 送信前に内容を確認することで、パーティションや実行名の誤り、Hydra のオーバーライドのタイプミスを最小限のコストで発見できます。

ステップ 5：送信する

同じコマンドを --dry-run なしで再実行します。起動スクリプトは .env を読み込み、 .rsync_lock/ の下にコードを rsync し、クラスター上の実行ディレクトリに slurm_batch_script_*.sh を書き込み、SSH 経由で sbatch を呼び出します。

./slurm_utils/launch_protein_binder_search.sh 22_DerF21
./slurm_utils/launch_laproteina_design_pipeline.sh
./slurm_utils/launch_laproteina_train.sh --config configs/training_local_latents.yaml

標準出力で Submitted batch job <ID> を確認します（ヘルパーは Submitted <stage> [i/N] with Job ID: <ID> をログに出力します）。training は --dependency=singleton を指定して --num-jobs 回送信されます（デフォルトは 5 件）。 すべての ID を記録してください。binder search と LaProteina design のパイプラインは ステージを順番に送信し、ステージ間で wait_for_job を実行するため、 次のステージの ID が利用可能になるまで呼び出し元は待機します。

ステップ 6：監視する

送信時に一度だけスナップショットを取得し、ユーザーに提示します。ポーリングはしないでください。 このスキルは再度呼び出しても時間がかかりません。

ssh "$CLUSTER_USER@$CLUSTER_HOST" "squeue -j <id1>,<id2>,... -u $CLUSTER_USER"

クラスター上のログの場所（実行ディレクトリ $CLUSTER_ROOT_REMOTE/<run_name>/ の下）：

スクリプト	ステージ	ログパス
binder search	生成	slurm_run_outputs/inf/slurm_<jobid>_<array>.{out,err}
binder search	フィルター	slurm_run_outputs/filter/slurm_<jobid>_<array>.{out,err}
binder search	評価	slurm_run_outputs/eval/slurm_<jobid>_<array>.{out,err}
binder search	分析	slurm_run_outputs/agg/slurm_<jobid>_<array>.{out,err}
LaProteina design pipeline	生成／評価／集約	slurm_run_outputs/{gen,eval,agg}/...
training	すべて	slurm_run_outputs/slurm_<jobid>.{out,err}

続けて確認する場合（ジョブがまだ実行中か、失敗したかなど）は、このスキルを再度呼び出すか、 ユーザー自身で ssh $CLUSTER_HOST を実行し、squeue -u $CLUSTER_USER／ sacct -j <id> を実行してもらいます。

ステップ 7：結果をダウンロードする

ユーザーからジョブが完了したと報告された場合：

• デフォルト（フラグなし）：パイプラインの終了後、launch_*.sh が結果を自動で rsync します。Binder 検索では、<run_name>-<YYYY_MM_DD_HH>/{inference,evaluation_results} にダウンロードし、script_utils/aggregate_successful_samples/aggregate_successful_samples.py を使って集約します。LaProteina 設計パイプラインでは、results_downloaded/<run_name>-<YYYY_MM_DD_HH>/ にダウンロードします。
• --skip-download が渡された場合：結果はクラスター上の $CLUSTER_ROOT_REMOTE/<run_name>/ に残ります。次のコマンドで手動で取得します：rsync -az $CLUSTER_USER@$CLUSTER_HOST:$CLUSTER_ROOT_REMOTE/<run_name>/ ./local_results/。
• --on-cluster が渡された場合：パイプラインはログインノードで実行され、結果はクラスター上の現在の作業ディレクトリに残ります。

トレーニングの結果は自動ではダウンロードされません。チェックポイントは $CLUSTER_ROOT_REMOTE/<run_name>/（設定されている場合は $CLUSTER_CKPT_PATH）に保存されます。

ステップ 8：slurm_manifest.json を出力する

./complexa_slurm/ にマニフェストを 1 つだけ配置し、再実行に必要なすべての情報をユーザーが 1 つのファイルで確認できるようにします。

{
  "timestamp": "2026-05-15T18:32:01Z",
  "workload": "binder_search",
  "launch_cmd": "./slurm_utils/launch_protein_binder_search.sh --runtime docker 22_DerF21",
  "cluster_host": "login.mycluster.example.com",
  "cluster_partition": "gpu,compute",
  "cluster_account": "my_slurm_account",
  "runtime": "docker",
  "run_name": "search_binder_pipeline-search-22_DerF21",
  "remote_run_dir": "/lustre/.../runs/search_binder_pipeline-search-22_DerF21",
  "sbatch_scripts": [
    "slurm_batch_script_gen.sh",
    "slurm_batch_script_filter.sh",
    "slurm_batch_script_eval.sh",
    "slurm_batch_script_analyze.sh"
  ],
  "slurm_job_ids": {"generation": "1234567", "filter": "...", "evaluation": "...", "analyze": "..."},
  "git_sha": "abc1234"
}

起動スクリプトはすでにリモートの実行ディレクトリに .githash を書き込むため、その SHA をローカルのマニフェストにも反映します。

ハードウェア

ワークロード	ジョブあたりのノード数	ノードあたりの GPU 数	タスクあたりの CPU 数	実行時間（デフォルト）	備考
Binder 検索（すべてのステージ）	1	1（gpus-per-node 1）	パイプライン YAML の ncpus_ による	04:00:00	ジョブアレイ。設定ごとに 1 ジョブ
LaProteina 設計パイプライン（すべてのステージ）	1	1	パイプライン YAML の ncpus_ による	02:00:00	ジョブアレイ。設定ごとに 1 ジョブ
トレーニング	nnodes_ による（例：12）	ngpus_per_node_ による（例：8）	ncpus_per_task_train_ による	04:00:00	単一ジョブの再キューイングチェーン（標準構成：Binder のファインチューニングで H100 を 12 × 8 = 96 基）

デフォルト値は、slurm_utils/slurm_helper.sh の generate_array_slurm_header／generate_train_slurm_header から取得されます。スクリプトごとの詳細は reference/slurm_workloads.md を参照してください。

トラブルシューティング

症状	原因	対処方法
ssh: connect: Permission denied (publickey)	パスワードなしの SSH が設定されていない／CLUSTER_SSH_KEY が間違っている	ssh-copy-id を実行するか、.env で CLUSTER_SSH_KEY=/abs/path/key を設定します
Directory ... already exists on remote	同じ run_name の前回の実行がクラスター上にあります	ssh $CLUSTER_HOST 'rm -rf $RUN_DIR' を実行するか、YAML の run_name を変更します
Container sqsh file not found on cluster	CLUSTER_CONTAINER_IMAGE のパスが間違っています	ssh $CLUSTER_HOST 'ls -lh <image>' で確認するか、レジストリ URL に切り替えます
Missing required fields in <pipeline_config>	YAML に gen_njobs／eval_njobs／run_name がありません	標準のパイプライン YAML から再導出します。下流のコピーは編集しないでください
INVALID_QOS／account ... not allowed in partition	CLUSTER_ACCOUNT に CLUSTER_PARTITION へのアクセス権がありません	アカウントに割り当てられたパーティションを選びます。ssh $CLUSTER_HOST 'sshare -A $CLUSTER_ACCOUNT' で確認します
すべてのアレイジョブが PENDING (Resources) のままになっている	パーティションの過負荷、または予約が間違っています	別のパーティションを試します。sinfo -p $CLUSTER_PARTITION で確認します

プリエンプション、コンテナの取得、チェックポイントの不足、rsync の失敗、ターゲットファイルの形式、--on-cluster とデフォルトの違いなどの詳細については、reference/troubleshooting.md を参照してください。

---

参考資料：

• reference/cluster_env.md — .env のセクション 5 の変数、デフォルト値、および各変数がない場合に発生する問題。
• reference/slurm_workloads.md — 起動スクリプトごとのフラグ一覧と sbatch の構成。コピーして使える例も記載しています。
• reference/troubleshooting.md — よくある障害の原因と対処方法。