complexa-design

Complexa Design スキル

4 段階の complexa design パイプライン全体を実行します。生成（フローマッチング + 検索） -> フィルタリング（報酬による上位 N 件） -> 評価（AF2/RF3 で再フォールド） -> 分析（成功率、FoldSeek/MMseqs による多様性）。設計の意図に合ったパイプライン設定を選び、 実行前に検証して、フォールディング中にチェックポイントの欠落が判明するのを防ぎます。 実行後は、再現可能なマニフェストと、設計ごとの成功 CSV を出力します。

このスキルでできること

• タンパク質標的に対するタンパク質バインダーの設計（AF2 報酬 + ColabDesign による再フォールド）。
• 小分子標的に対するリガンドバインダーの設計（RF3 報酬 + RF3 による再フォールド）。
• リガンドのコンテキストを用いた AME モチーフの足場化（モチーフ + リガンド特徴量、RF3）。
• 検索ベースの最適化：single-pass、best-of-n、beam-search、fk-steering、mcts。
• 再フォールドバックエンド：ColabDesign（AF2）、RF3、Boltz2、ESMFold（高速な反復）。
• result_type ごとのしきい値による合格率と多様性の分析。

ステップ 1：事前確認

設計を開始する前に、必ず共通の事前確認を実行してください。生成には GPU と適切なチェックポイントが必要で、 評価には AF2/RF3 の重みとツールのバイナリが必要です。ホストで選択したパイプラインを実行できない場合は、 早期に中止してください。

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

./complexa_setup/preflight.json を読み込み、選択したパイプラインに必要な以下の項目が欠けている場合は中止してください。

• gpu.available: false -> すべてのパイプラインが失敗します。
• gpu.vram_gb < 40 -> デフォルトの batch_size: 16 では生成時に OOM が発生します。8 に下げてください。
• ckpts.complexa[.ckpt] -> タンパク質バインダーに必要です。
• ckpts.complexa_ligand[.ckpt] -> リガンドバインダーに必要です。
• ckpts.complexa_ame[.ckpt] -> AME に必要です。
• env.AF2_DIR が未設定 -> タンパク質バインダーのデフォルト評価（colabdesign）が失敗します。
• env.RF3_CKPT_PATH または env.RF3_EXEC_PATH が未設定 -> リガンドバインダー／AME のデフォルト評価（rf3_latest）が失敗します。

チェックポイントがない場合は、complexa-setup を案内し、ユーザーに最初に complexa download --complexa-<variant> を実行してもらってください。

ステップ 2：パイプラインを選ぶ

Complexa にはデフォルトのパイプライン（タンパク質バインダー）が 1 つと、拡張機能 （リガンドバインダー、AME／酵素）が 2 つあります。パイプラインは、 complexa design に渡す configs/search_*_pipeline.yaml によって完全に選択されます。 各 YAML には、それぞれのモデルチェックポイント、オートエンコーダー、ターゲット辞書、デフォルトの報酬、 デフォルトの再フォールドバックエンドが設定されています。パイプラインの切り替えは、 「設定ファイルのパスを変更すると、ターゲット名は別の辞書から読み込まれる」だけです。

デフォルト — タンパク質バインダー

complexa design configs/search_binder_local_pipeline.yaml \
    ++run_name=pdl1_v1 ++generation.task_name=02_PDL1

ユーザーが「X 用のバインダーを設計」「PDL1 バインダー」「de novo バインダー」 「標的に結合するタンパク質を設計」などと言った場合、つまり標的がタンパク質表面である場合に使用します。 この設定では complexa.ckpt + complexa_ae.ckpt を指定し、 configs/targets/targets_dict.yaml から標的を読み込み、AF2（af2folding）で報酬を計算し、 SolubleMPNN で逆フォールディングを行い、ColabDesign / AF2 で評価します。 ユーザーが指定していない場合は、こちらを使用します。

拡張機能 A — リガンドバインダー（小分子ポケット）

complexa design configs/search_ligand_binder_local_pipeline.yaml \
    ++run_name=v11_v1 ++generation.task_name=39_7V11_LIGAND \
    ++metric.binder_folding_method=rf3_latest

ユーザーが「リガンドバインダー」「小分子ポケット」「SMILES 標的」 「ATP 結合タンパク質」と言った場合、または _LIGAND で終わるターゲット名や、 FAD / SAM / OQO / 7V11 などのファミリーに属するターゲット名を指定した場合に切り替えます。 この設定ではLoRA も有効化されます（r=32、lora_alpha=64）。これは公開済みのリガンドチェックポイントに必要です。 lora: ブロックは変更しないでください。

拡張機能 B — AME／モチーフ + リガンド（酵素の足場化）

complexa design configs/search_ame_local_pipeline.yaml \
    ++run_name=ame_chm ++generation.task_name=M0096_1chm

ユーザーが「リガンド近傍にモチーフの足場を作る」「活性部位の設計」「酵素の足場化」 「AME」と言った場合、または M0024_1nzy、M0096_1chm などのターゲット （M####_<pdb> 形式の AME タスク名）を指定した場合に切り替えます。この設定では env_vars.USE_V2_COMPLEXA_ARCH=True を設定し（CLI ランナーがサブプロセスに注入します）、 MotifFeatures と LigandFeatures の両方を使用します。デフォルトの検索は single-pass です。CompositeRewardModel（ame_generate.yaml でコメントアウトされています）も有効にする場合に限り、 best-of-n に切り替えてください。

パイプライン早見表 — 切り替えると何が変わるか

設定項目	タンパク質バインダー（デフォルト）	リガンドバインダー	AME（酵素）
パイプライン YAML	configs/search_binder_local_pipeline.yaml	configs/search_ligand_binder_local_pipeline.yaml	configs/search_ame_local_pipeline.yaml
モデル ckpt	complexa.ckpt	complexa_ligand.ckpt	complexa_ame.ckpt
オートエンコーダー ckpt	complexa_ae.ckpt	complexa_ligand_ae.ckpt	complexa_ame_ae.ckpt
ターゲット辞書	configs/targets/targets_dict.yaml	configs/targets/ligand_targets_dict.yaml	configs/design_tasks/ame_dict_v2.yaml
タスク名のパターン	<NN>_<NAME>（例：02_PDL1、22_DerF21）	<NN>_<PDB>_LIGAND（例：39_7V11_LIGAND）	M####_<pdb>（例：M0096_1chm）
USE_V2_COMPLEXA_ARCH	（未設定 → v1）	（未設定 → v1）	"True"（YAML で設定）
LoRA	（なし）	必須（r=32, alpha=64）	必須
デフォルトの検索アルゴリズム	best-of-n	best-of-n	single-pass
報酬モデル	AF2（af2folding）	RF3（rf3folding）	null（デフォルトでは報酬なし）
逆フォルダー	soluble_mpnn	ligand_mpnn	ligand_mpnn
デフォルトのリフォールドバックエンド	colabdesign（AF2）	rf3_latest	rf3_latest
分析の result_type	protein_binder	ligand_binder	motif_ligand_binder
必須 ckpt（complexa download）	--complexa --all（コミュニティ版では AF2）	--complexa-ligand --all（コミュニティ版では RF3）	--complexa-ame --all（コミュニティ版では RF3）

パイプラインごとの詳細（報酬の重み、成功しきい値、分析モード）については、reference/pipelines.md を参照してください。

ステップ 3：パラメーターを集める

AskUserQuestion を使って、実行ごとに変わる 4 つのパラメーターを入力します。ユーザーに希望がない場合は、妥当な本番環境向けの設定をデフォルトにします。

• ターゲット名 — 該当する辞書のキーである必要があります（タンパク質バインダーでは targets_dict.yaml、リガンドでは ligand_targets_dict.yaml、AME では ame_dict_v2.yaml）。ユーザーが辞書にないターゲットを指定した場合は、まず complexa-target に引き継いで追加します。
• 実行名 — 出力ディレクトリ名の末尾に付ける短い識別子です（例：pdl1_v1）。
• 検索アルゴリズム — 本番環境では、デフォルトを beam-search、beam_width=8、n_branch=4 にします。簡単なスモークテストには single-pass を使います。
• 評価リフォールドバックエンド — タンパク質バインダーのデフォルトは colabdesign（AF2）、リガンド／AME のデフォルトは rf3_latest です。素早く反復する場合は esmfold を使います（精度は劣りますが、サンプルあたり数秒です）。

ステップ 4：検証する

実行前に検証します。時間はほとんどかからず（数秒）、不足している ckpt、環境変数、未知のオーバーライドキー、ターゲットエントリーの欠落を検出できます。これらがあると、生成に何時間もかかった後の評価中にパイプラインが中断されます。

complexa validate design configs/search_binder_local_pipeline.yaml \
    ++generation.task_name=02_PDL1 \
    ++metric.binder_folding_method=colabdesign

検証に失敗すると、バリデーターはゼロ以外の値を返し、合否レポートを表示します。問題なく通るまで、提案されたオーバーライドを使ってコマンドを再実行してください。

ステップ 5：パイプラインを実行する

4 段階の実行全体には complexa design が適しています。これは generate → filter → evaluate → analyze を、共有の実行名、ログディレクトリ、複数 GPU の分割設定を使って、順次サブプロセスとして実行します（src/proteinfoundation/cli/cli_runner.py の run_design_pipeline を参照）。手動で再実装すると、ステージごとのログ振り分けと進捗表示が失われます。

++（強制）Hydra オーバーライドを使います。これらはすべてのステージに適用されます。最小限の本番環境向けタンパク質バインダーの実行コマンドは次のとおりです。

complexa design configs/search_binder_local_pipeline.yaml \
    ++run_name=pdl1_v1 \
    ++generation.task_name=02_PDL1 \
    ++generation.search.algorithm=beam-search \
    ++generation.search.beam_search.beam_width=8 \
    ++metric.binder_folding_method=colabdesign

リガンドバインダー／AME の場合は、ステップ 2 の早見表に従ってパイプライン YAML とターゲット名を切り替えます。上記のその他のオーバーライドはパイプラインに依存しないため、そのまま再利用できます。

ログを ./logs/ ではなく端末に出力するには、--verbose を追加します。このスキルは進捗をポーリングしません。状況を確認したい場合、ユーザーは再度呼び出す必要があるため、complexa status と ./logs/design_pipeline_*/ を案内してください。

モジュールの直接呼び出し（デバッグ用フォールバック）

パイプラインのオーケストレーションを使わずに単一のステージをデバッグするには、基盤となる Hydra モジュールを直接呼び出します。complexa generate CONFIG は、これをラップしてログを記録する サブプロセスにすぎません:

python -m proteinfoundation.generate \
    --config-path "$(realpath configs)" \
    --config-name search_binder_local_pipeline \
    ++run_name=debug_pdl1 \
    ++generation.task_name=02_PDL1

proteinfoundation.{filter,evaluate,analyze} も同じパターンです。ipdb をアタッチしたい場合や、nsys 配下で実行したい場合、パイプラインのログディレクトリをスキップしたい場合にこれを使います。 通常のワンショット実行には complexa generate/filter/evaluate/analyze を推奨します（ログ記録と並列ジョブ分割が無料で得られます）。

AME 固有の注意点（AME を RF3 リフォールドで実行する場合）: RF3 は CCD コードに基づいてリガンドの欠落原子を補完しようとするため、RMSD 計算で形状エラーが発生し、誤った構造になります。RF3 が PDB を参照する前に、リガンド残基を L:0 にリネームして、RF3 がそれを汎用リガンドとして扱い、原子補完をスキップするようにしてください。AME 生成の出力ですでにこのようにリガンドがエンコードされている場合（正規の Complexa パイプラインではそうなっています）、追加の手順は不要です。そうでない場合は、atomworks.io を使って各 PDB をパッチしてください:

from atomworks.io import load_any, to_pdb_file
atom_array = load_any("my_design.pdb")[0]
ligand_mask = atom_array.chain_id == "A"
atom_array.res_name[ligand_mask] = "L:0"
to_pdb_file(atom_array, "my_design_rf3_ready.pdb")

RF3 バックエンドで AME 出力を complexa-evaluate-pdbs スキルにパイプする場合も同様です。AF2/colabdesign リフォールドや AME 以外のパイプラインではリネームをスキップしてください。

デフォルト設定（nsteps=400、beam_width=8、batch_size=16、100 デザイン、colabdesign 評価）での実時間は、単一の A100/H100 で約 30～120 分です。

ステップ 6: 結果の収集

出力は 2 つのディレクトリに格納されます。両方を提示してください:

ls ./inference/${CONFIG_STEM}_${TASK}_*${RUN_NAME}/   # generated PDBs + filter
ls ./evaluation_results/${RUN_NAME}/                  # per-design CSV + analysis

統合結果の CSV を読み取り、要約します:

ls ./evaluation_results/*/binder_results_*_combined.csv
ls ./evaluation_results/*/motif_binder_results_*_combined.csv  # AME
ls ./evaluation_results/*/res_filter_*_pass_*.csv              # success rate
ls ./evaluation_results/*/res_div_foldseek_*.csv               # FoldSeek diversity

成功率は res_filter_binder_pass_*.csv から、デザインごとのメトリクス（interface pAE、pLDDT、scRMSD）は統合 CSV から、FoldSeek TM-score の多様性は res_div_foldseek_*.csv から取得します。i_pAE（タンパク質バインダー）または min_ipAE（リガンドバインダー）で上位 N 件のデザインを報告してください。

ステップ 7: マニフェストの出力

実行を再現できるように、結果の隣に JSON マニフェストを配置します。共有ヘルパーがコマンド、設定、git SHA、および結果 CSV へのポインタをキャプチャします。

python3 .claude/skills/_shared/scripts/write_manifest.py \
    --output-dir ./evaluation_results/${RUN_NAME} \
    --command "complexa design configs/search_binder_local_pipeline.yaml ++run_name=${RUN_NAME} ++generation.task_name=${TASK}" \
    --skill complexa-design \
    --out ./run_manifest.json

マニフェストのパスと結果 CSV をユーザーに提示してください。

よく使われるオーバーライド

実行の約 90% をカバーする 10 個のオーバーライドです。完全なリファレンス（すべてのキー、型、デフォルト値）は reference/overrides.md にあります。

オーバーライド	デフォルト	制御する内容
++generation.task_name=<name>	(設定ごと)	どのターゲット / AME タスク向けにデザインするか
++run_name=<str>	(設定のステム)	出力ディレクトリのサフィックスと CSV タグ
++generation.search.algorithm=beam-search	best-of-n（バインダー/リガンド）、single-pass（AME）	探索戦略
++generation.search.beam_search.beam_width=8	4	ビームサーチの幅（大きいほど高品質なデザイン、遅くなる）
++generation.args.nsteps=200	400	拡散ステップ数（少ないほど高速、品質は低下）
++generation.dataloader.batch_size=8	16（バインダー/リガンド/AME）	40GB GPU では 8 に下げる
++generation.filter.filter_samples_limit=500	1000	フィルタリング後に保持する上位 N 件のサンプル
++metric.binder_folding_method=esmfold	colabdesign（バインダー）、rf3_latest（リガンド/AME）	評価リフォールドバックエンド
++metric.num_redesign_seqs=8	2	デザインごとの ProteinMPNN/LigandMPNN/SolubleMPNN 配列数
++aggregation.success_thresholds.i_pAE.threshold=10.0	7.0（タンパク質バインダー）	成功基準を緩める / 厳しくする

ハードウェア要件

リソース	最小構成	推奨構成
GPU	CUDA GPU × 1、VRAM 40 GB	A100 / H100 / L40S、VRAM 80 GB
CPU	16	24（各パイプライン設定の ncpus_ のデフォルト値）
ディスク	./inference/ + ./evaluation_results/ に 50 GB	スイープ実行用に 200 GB
RAM	32 GB	64 GB 以上

デザイン 100 件、beam_width=8、デフォルトの nsteps=400 での標準的な実行時間：

• タンパク質バインダー + colabdesign によるリフォールド：約 60～120 分（A100/H100 × 1）。
• リガンドバインダー + RF3 によるリフォールド：約 90～180 分（大半は RF3 が占めます）。
• AME + RF3 によるリフォールド：約 120～240 分。
• 任意のパイプライン + ESMFold によるリフォールド：約 30～60 分（高速な反復に適しています）。

2 GPU のホストで gen_njobs=2 と eval_njobs=2 に設定すると、実行時間を半分に短縮できます。パイプラインごとの VRAM 表については .claude/skills/_shared/reference/hardware.md を参照してください。

トラブルシューティング（よくあるケース）

症状	原因	対処方法
generate で CUDA out of memory が発生する	40GB GPU では batch_size: 16 が大きすぎる	++generation.dataloader.batch_size=8
evaluate で CUDA out of memory が発生する	AF2 / RF3 のバッチ処理が過剰	++eval_njobs=1 と ++metric.num_redesign_seqs=2
InterpolationKeyError: AF2_DIR	colabdesign による評価を行うが、.env に AF2_DIR が設定されていない	.env に AF2_DIR を設定するか、++metric.binder_folding_method=esmfold を指定する
InterpolationKeyError: RF3_CKPT_PATH	RF3 による評価を行うが、RF3 がインストールされていない	complexa download --all を実行するか、評価バックエンドを切り替える
KeyError: 'task_name' not in target_dict_cfg	ターゲットが targets_dict.yaml / ligand_targets_dict.yaml / ame_dict_v2.yaml にない	complexa-target スキルを使って追加する
成功のしきい値を満たすデザインが 0 件	このターゲットに対してデフォルト値が厳しすぎる	++aggregation.success_thresholds.* で緩和する

全ケース（チェーン ID の不一致、ホットスポット残基、RF3 用のリガンド残基のリネーム、逆折りたたみモデルの不足など）については、 reference/troubleshooting.md を参照してください。

---

パイプラインごとの詳細（使用するモデル、報酬、逆折りたたみ、評価バックエンド、 result_type、LoRA の設定、USE_V2_COMPLEXA_ARCH の切り替え）については、 reference/pipelines.md を参照してください。

すべてのオーバーライドのリファレンス（型、デフォルト値、例、効果を含む、各 generation.*、metric.*、 aggregation.* キー）については、reference/overrides.md を参照してください。

すべてのトラブルシューティングケース（原因 + 対処方法 + 出典）については、 reference/troubleshooting.md を参照してください。