proteina-complexa

name	proteina-complexa
description	Design protein binders, ligand binders, and motif scaffolds using the Proteina-Complexa generative flow-matching framework (NVIDIA, ICLR 2026 Oral). Use when running binder design pipelines, adding custom targets, configuring reward models, evaluating designs with AF2/RF3, analyzing results, troubleshooting Hydra configs or GPU/Triton issues, or preparing candidates for experimental validation.

Proteina-Complexa

Use this skill to work effectively with the Proteina-Complexa protein design framework at /home/qiao/md/Proteina-Complexa.

Load the right reference first

• Read references/architecture.md for the generative model architecture, flow matching, latent autoencoder, reward models, and the four-stage pipeline design.
• Read references/setup-and-operations.md for environment activation, checkpoint paths, .env configuration, Triton fixes, and operational debugging.
• Read references/repo-map.md for file ownership, source entry points, config hierarchy, and the fastest path to the right file.
• Read references/design-workflows.md for end-to-end binder design workflows: protein binder, ligand binder, AME motif scaffolding, custom target definition, evaluation, analysis, and visualization.
• Read references/workstation-config.md for this workstation's verified paths, GPU setup, known blockers (AF2 reward), and environment workarounds.

Start by classifying the task

Classify the request into one of these buckets before editing:

• Environment setup or checkpoint management
• New target preparation and config
• Binder generation (protein, ligand, or AME)
• Filtering, evaluation, or analysis
• Reward model configuration (AF2, RF3, TMOL)
• Config tuning (Hydra overrides, sweep system)
• Result visualization and candidate selection
• Training or fine-tuning
• Troubleshooting (Triton, OOM, missing weights, config errors)

Then load only the references that match that bucket.

Keep these invariants

• The project root is /home/qiao/md/Proteina-Complexa. Always cd there and source .venv/bin/activate && source env.sh before any complexa command.
• The pipeline is a four-stage process: generate → filter → evaluate → analyze. complexa design runs all four; individual stages can be run separately.
• Hydra + OmegaConf manages all configuration. Environment variables in .env are resolved at runtime via ${oc.env:VAR}. A missing variable causes InterpolationKeyError.
• Three model variants exist, each with its own checkpoint pair (model + autoencoder): Protein Binder, Ligand Binder (LoRA), AME (LoRA).
• On this workstation, AF2 reward is not usable (missing jax/atomworks in the UV venv). Use RF3 reward instead. The run_complete_pipeline.sh script already disables AF2 reward.
• Always set export CC=/usr/bin/gcc && export CXX=/usr/bin/g++ and clear ~/.triton/cache/* before evaluation to avoid Triton compiler errors.
• Config overrides use ++key=value (Hydra syntax). Use ~key to remove a config node (e.g., "~generation.reward_model.reward_models.af2folding").
• gen_njobs and eval_njobs control GPU parallelism. Set to 1 for single-GPU operation.

Use this default workflow

1. Identify the user's design goal and which pipeline type applies (protein binder, ligand binder, AME, monomer motif).
2. Read the relevant reference file before changing code or configs.
3. Map the request to the correct entry point:
   • Environment: env.sh, .env, env/build_uv_env.sh
   • Target setup: configs/targets/targets_dict.yaml, configs/targets/ligand_targets_dict.yaml
   • Generation: configs/search_binder_local_pipeline.yaml (protein), search_ligand_binder_local_pipeline.yaml (ligand), search_ame_local_pipeline.yaml (AME)
   • Evaluation: configs/evaluate.yaml, configs/evaluate_from_pdb_dir.yaml, configs/evaluate_narl_strict.yaml
   • Analysis: configs/analyze.yaml, custom scripts in narl_binder_analysis/analysis/
   • Full pipeline: run_complete_pipeline.sh
   • Reward models: configs/pipeline/binder/binder_generate.yaml, configs/pipeline/ligand_binder/ligand_binder_generate.yaml
4. Make the smallest coherent change and verify with complexa validate design <config> before running.
5. For visualization, follow the user's global style rules: plt.style.use('seaborn-v0_8-whitegrid'), dpi=300, NarQ=#9B8CFF, NarL=#FFB347, threshold=#D0021B.

Use this mental model

Target PDB + Hotspots
  │
  │  configs/targets/targets_dict.yaml
  ▼
Generate (flow matching + reward scoring)
  │  complexa generate / search algorithm (beam, MCTS, best-of-N)
  │  Reward: RF3 (default on this workstation) or AF2
  ▼
Filter (dedup + reward threshold)
  │  complexa filter
  ▼
Evaluate (structure prediction refolding)
  │  complexa evaluate
  │  RF3 or AF2/ColabDesign → iPTM, i_pAE, pLDDT, scRMSD
  ▼
Analyze (aggregate + success filtering + diversity)
  │  complexa analyze
  ▼
Visualization + Candidate Selection
  │  Python/PyMOL scripts → Top 8-12 for wet-lab
  ▼
Experimental Validation

Ask these debugging questions first

• Is the .venv activated and env.sh sourced?
• Are CC=/usr/bin/gcc and CXX=/usr/bin/g++ exported? Is ~/.triton/cache cleared?
• Does complexa validate design <config> pass without InterpolationKeyError?
• Are checkpoint files real weights (multi-MB), not placeholders (94-105 bytes)?
• Is the target name correct and present in targets_dict.yaml?
• Is gen_njobs/eval_njobs set to match available GPUs?
• Is the failure in generation (reward model), evaluation (RF3/AF2), or analysis (missing CSVs)?

Use these references by task type

• Use references/setup-and-operations.md for environment, checkpoints, .env, Triton fixes, Docker, and verification.
• Use references/architecture.md for model internals, flow matching, autoencoder, reward models, search algorithms, and config composition.
• Use references/repo-map.md for locating source files, config files, and understanding the Hydra composition hierarchy.
• Use references/design-workflows.md for running protein/ligand/AME binder design end-to-end, defining custom targets, evaluation metrics, and visualization.
• Use references/workstation-config.md for this machine's verified paths, GPU config, AF2 blocker status, and production scripts.