complexa-sweep

complexa-sweep

Proteina-Complexa の設計パイプラインで、直積パラメーターのスイープを実行します。configs/sweeps/ からスイーパー YAML を選ぶか作成し、script_utils/generate_inference_configs.py で N 個の推論設定に展開します。次に、それらの設定を使って complexa design を繰り返し実行し、設定ごとの成功指標を集計して、ランキング付きのサマリー CSV とマニフェストを作成します。

重要: complexa design CLI は --sweeper を直接受け付けません。スイープは script_utils/generate_inference_configs.py で実行し、このスクリプトはスイープの組み合わせごとに configs/inference_configs/inf_{idx}_{run_name}.yaml を 1 つずつ書き出します。その後、生成された設定を使って complexa design を繰り返し実行します。

このスキルでできること

• configs/sweeps/ から既存のスイーパー YAML（beam_width、bb_ca_temperature、search_replicas、example）を選択します。
• 任意のドット記法の軸（直積）を使って、新しいスイーパー YAML を作成します。
• script_utils/generate_inference_configs.py で N 個の推論・評価設定のペアを生成します。
• 生成された設定を使って complexa design を繰り返し実行します（単一 GPU では一度に 1 つずつ、マルチ GPU ホストでは設定リストを CUDA_VISIBLE_DEVICES ごとに分割して並列実行できます）。
• 設定ごとの出力ディレクトリをたどり、それぞれの analyze ステップの CSV を解析します。
• sweep_summary.csv（設定ごとに 1 行。軸の値、成功率、平均 iPAE、多様性を含む）と sweep_manifest.json を出力します。
• 成功率が最も高い設定とパレートフロンティア（実行時間と成功率）を特定します。

Step 1: 事前確認

bash .claude/skills/_shared/scripts/preflight.sh

./complexa_setup/preflight.json を読み取ります。スイープでは、設定数に応じて GPU 実行時間が増加します。実行を開始する前に、ユーザーにコストを確認してください：

「このスイープでは、N 個の設定 × 設定あたり約 M 分 ≈ 合計 TOTAL GPU 時間かかります。実行してもよろしいですか？（y / 減らす / キャンセル）」

gpu.available=false の場合は停止してください。CPU ではスイープを実行できません。

Step 2: パイプラインとターゲットを選ぶ

complexa-design と同じ対話を使用してください。ここで繰り返さないでください。手順 2（「パイプラインを選ぶ」）と手順 3（「パラメーターを収集する」）については、.claude/skills/complexa-design/SKILL.md を参照してください。以下を取得します：

• pipeline_config_name — 例：search_binder_local_pipeline（デフォルト）、search_ligand_binder_local_pipeline、search_ame_local_pipeline。
• task_name — 例：02_PDL1、22_DerF21、39_7V11_LIGAND。--override generation.task_name=<task> として渡します。
• run_name — 出力ディレクトリ名に使う短いタグ。

Step 3: スイーパー YAML を選ぶか作成する

スイーパー YAML は configs/sweeps/ にあります。各キーはドット記法の Hydra パスで、各値はリストです。直積により N 個の設定が生成されます。

用意されているスイーパー

ファイル	軸	値	設定数
configs/sweeps/beam_width.yaml	generation.search.beam_search.beam_width	1、2、4、8	4
configs/sweeps/bb_ca_temperature.yaml	generation.model.bb_ca.simulation_step_params.sc_scale_noise	0.1、0.4	2
configs/sweeps/search_replicas.yaml	generation.search.best_of_n.replicas	1、4、16、64	4
configs/sweeps/example.yaml	beam_width × nsteps	(2,4) × (200,400)	4

ユーザーの意図に合うものがあれば、そのまま使用してください。なければ、新しいファイルを作成してください。

新しいスイーパーを作成する

複数軸の最小限の例（configs/sweeps/my_sweep.yaml に保存）：

# 3 beam widths × 2 nsteps = 6 configs
generation.search.beam_search.beam_width:
  - 2
  - 4
  - 8

generation.args.nsteps:
  - 200
  - 400

ルール（script_utils/generate_inference_configs.py:load_sweeper_file に基づく）：

• 最上位はマッピングのみです。キーにはドット記法の Hydra パスを使用します。
• 値は リスト である必要があります。スカラー値は単一要素のリストに自動的に変換されます（次元を追加せずに値を固定します）。
• 直積：設定の合計数 = 各リストの長さの積。4 つの値を持つ軸が 2 つある場合、設定数は 16 です。必要な予算を見積もってください。
• キーがスイーパーファイルと --override の両方にある場合、オーバーライドが優先され、その軸は 1 つに固定されます。

スイープ対象キーの全一覧（一般的な範囲、コスト倍率、改善・悪化する項目）については、reference/sweep_axes.md を参照してください。

生成前のドライランプレビュー

まず、必ず設定数を確認します。

python script_utils/generate_inference_configs.py \
    --config_name search_binder_local_pipeline \
    --sweeper configs/sweeps/my_sweep.yaml \
    --override generation.task_name=22_DerF21 \
    --run_name my_sweep \
    --dryrun

出力には各軸と値のリストがすべて表示され、DRY RUN — would generate N config pair(s) と出力されます。

Step 4: 設定を生成して complexa design をループ実行する

ドライランの内容に問題がなければ、--dryrun を削除して、configs/inference_configs/ と configs/eval_configs/ の下に inf_{idx}_{run_name}.yaml と eval_{idx}_{run_name}.yaml のペアを生成します。次に、推論設定を順に complexa design で実行します。

# 1. Generate one inf_*.yaml + one eval_*.yaml per combination.
python script_utils/generate_inference_configs.py \
    --config_name search_binder_local_pipeline \
    --sweeper configs/sweeps/my_sweep.yaml \
    --override generation.task_name=22_DerF21 \
    --run_name my_sweep

# 2. Loop complexa design over each generated inference config.
for cfg in configs/inference_configs/inf_*_my_sweep.yaml; do
    complexa design "$cfg" || echo "FAILED: $cfg"
done

これにより、1 台の GPU でスイープが逐次実行されます。実行時間が実行回数 N × 1 回あたりの時間になることを、ユーザーに正直に伝えてください。

マルチ GPU ホスト（任意の高速化）

K 台の GPU を搭載したホストでは、設定リストを K 分割し、GPU ごとにループを並列で実行します。各 complexa design 呼び出しは、デフォルトの gen_njobs=1 / eval_njobs=1 で GPU を 1 台だけ使用するため、CUDA_VISIBLE_DEVICES で割り当てることで、GPU の競合を防げます。

CONFIGS=(configs/inference_configs/inf_*_my_sweep.yaml)
N=${#CONFIGS[@]}; K=4   # 4 GPUs
for gpu in $(seq 0 $((K-1))); do
    (
        for i in $(seq $gpu $K $((N-1))); do
            CUDA_VISIBLE_DEVICES=$gpu complexa design "${CONFIGS[$i]}" \
                || echo "FAILED on GPU $gpu: ${CONFIGS[$i]}"
        done
    ) &
done
wait

各 complexa design 呼び出しで複数の GPU を使うことを意図しており、互いに競合しないようにする手段がある場合に限り、ループに gen_njobs / eval_njobs の上書きを追加します。

Step 5: 結果を収集する

スイープした設定ごとに、それぞれの ./inference/inf_{idx}_{run_name}/ ディレクトリに出力が書き込まれます。解析ステップでは、./evaluation_results/eval_{idx}_{run_name}/results_*.csv に出力が書き込まれます。スイープが完了したら、次の処理を行います。

ls -d ./inference/inf_*_my_sweep/
ls ./evaluation_results/eval_*_my_sweep/results_*.csv

各設定について、解析 CSV を解析します（生成されたバインダーごとに 1 行）。ランキングに使用する標準列は、i_pae、i_plddt、sc_rmsd、binder_seq、passes_filter（bool）です。passes_filter がない場合は、ユーザーが選択したしきい値（デフォルト：i_pae < 10、i_plddt > 0.7、sc_rmsd < 2.0。ユーザーに確認してください）を使って成功フラグを導出します。

Step 6: 設定をランク付けする

実行ディレクトリに sweep_summary.csv を出力します。設定ごとに 1 行を出力します。

列	計算方法
config_id	inf_{idx}_{run_name} の {idx}
<axis_1>、<axis_2>、...	この組み合わせでスイープした値（設定ごとの inf_*.yaml から読み取ります）
n_samples	解析 CSV の行数
success_rate	passes_filter.mean()
mean_i_pae	i_pae.mean()（小さいほど良好）
mean_i_plddt	i_plddt.mean()（大きいほど良好）
diversity_score	ユニークな配列の数 / n_samples（利用できる場合は TM スコアによるクラスタリングを使用します）
wall_clock_min	設定ごとのログのタイムスタンプから取得

次に、以下を報告します。

• 最良の設定 = success_rate が最大の設定。同率の場合は mean_i_pae（小さい方）で決着させます。
• パレートフロンティア（wall_clock_min、success_rate）：他の設定より実行時間が短く、かつ成功率が高い設定がない場合、その設定はフロンティア上にあります。

最良の設定とフロンティアをターミナルに出力します。完全な表は sweep_summary.csv に保存します。

Step 7: マニフェストを出力する

再実行できるように、解決済みの呼び出し内容と出力を記録します。共有ヘルパーが受け取るのは単一の --output-dir です（CSV を検索し、実行時の .hydra/ から Hydra 設定を取得します）。そのため、最良の設定の評価ディレクトリを指定し、その実行に使った親の complexa design コマンドを渡して呼び出します。

BEST_ID=4   # from Step 6 ranking
python3 .claude/skills/_shared/scripts/write_manifest.py \
    --output-dir ./evaluation_results/eval_${BEST_ID}_my_sweep \
    --command "python script_utils/generate_inference_configs.py --config_name search_binder_local_pipeline --sweeper configs/sweeps/my_sweep.yaml --override generation.task_name=22_DerF21 --run_name my_sweep && for cfg in configs/inference_configs/inf_*_my_sweep.yaml; do complexa design \"\$cfg\"; done" \
    --skill complexa-sweep \
    --out ./sweep_runs/my_sweep/sweep_manifest.json

マニフェストとともに、Step 6 でランク付けした sweep_summary.csv を ./sweep_runs/my_sweep/sweep_summary.csv に保存し、両方のパスをユーザーに提示します。

推奨されるスイープのレシピ

症状	ここをスイープ	理由
品質が不十分	beam_width × nsteps（出発点として example.yaml を使用）	どちらも計算量を増やすことで品質が向上します。目標を達成できる最も低コストの組み合わせを見つけます。
遅すぎる／高速化したい	beam_width=4 を固定して、nsteps を減らす（例：[100, 200, 400]）	成功率を維持できる最小の nsteps を見つけます。
モード崩壊／多様性が低い	generation.model.bb_ca.simulation_step_params.sc_scale_noise（bb_ca_temperature.yaml を使用）	ノイズを増やすと、バックボーンの多様性が高まります。
報酬の過学習（報酬は高いが、指標が悪い）	generation.reward_model.reward_models.af2folding.reward_weights.{i_pae, plddt} の比率	複合報酬のバランスを調整します。
1 つの設定で統計的な堅牢性を得たい	search_replicas.yaml（best_of_n.replicas）	同じ設定でサンプル数を増やし、成功率の推定をより正確にします。
アルゴリズムを比較したい	generation.search.algorithm を [single-pass, best-of-n, beam-search, fk-steering] の範囲で変更	検索方式を比較します。それ以外の設定は固定します。

ハードウェア

スイープ全体の GPU 時間 ＝ N_configs × per_run_GPU_time です。A100 1 基での search_binder_local_pipeline の実行は、およそ 30～90 分です（バインダーの長さと nsteps によって異なります）。4 軸 × 4 値のスイープでは、256 configs × 約 60 分 ＝ 約 256 GPU-hours となります。この規模では、Step-4 のシャーディングパターンを使えるマルチ GPU ホストを計画してください。

1 回あたりの実行時間のベースラインと VRAM の最小要件については、.claude/skills/_shared/reference/hardware.md を参照してください。

トラブルシューティング

症状	原因	対処方法
generate_inference_configs.py で Sweeper file not found が発生する	誤った CWD を基準にパスが解決されている	リポジトリのルートからの相対パスを使用するか、絶対パスを指定してください。
Sweeper YAML must be a mapping	YAML のトップレベルがリストまたはスカラーになっている	key: [v1, v2] 形式のマッピングに書き換えてください。
No configs were generated	値リストのいずれかが空の [] になっている	スイーパーファイルに key: [] の行があります。値を 1 つ以上追加してください。
complexa design が --sweeper を拒否する	エントリーポイントを混同している	CLI は --sweeper を受け付けません。先に generate_inference_configs.py を使用し、生成された設定に対して complexa design をループ実行してください。
オーバーライドによってスイープ軸が気づかないうちに 1 つに絞られる	--override key=v がスイープキーを上書きしている	オーバーライドを削除するか、スイーパーファイルから対応するキーを削除してください。
ループ内の 1 つの設定が失敗しても、スイープが続行される	Step 4 の || echo "FAILED…" がエラーを握りつぶしている	失敗した inf_*.yaml を単独で再実行し、./logs/ にある設定ごとのログを確認してください。ランキングから失敗した config_id を除外してください。

---

各軸の参考情報（一般的な範囲、コスト、改善・悪化する項目）については、reference/sweep_axes.md を参照してください。

ユーザー向けのスイープシステムの概要（設定の生成、出力レイアウト）については、docs/SWEEP.md を参照してください。