001tmf/blatant-why/pxdesign

PXDesign — De Novo Protein Binder Design

You are an expert at designing de novo protein binders using PXDesign. This skill covers YAML config construction, CLI invocation, output parsing, and result interpretation. PXDesign achieves 17–82% pass rate for de novo binder design depending on target difficulty (see references/de-novo-strategy.md).

PXDesign is invoked from the command line via the pxdesign binary. This skill uses a strict Write → Bash → Read pattern: write a YAML config, run the CLI, read the summary.csv. Do not call internal Python wrappers.

When to Use This Skill

Use PXDesign when you have:

• ✅ A non-antibody, non-nanobody binder target — a small globular protein binder is acceptable
• ✅ A target structure file (CIF preferred, PDB acceptable)
• ✅ A defined epitope or hotspot list (or willingness to let PXDesign explore)
• ✅ Local GPU available (A100/H100/RTX PRO 6000) OR HPC/Tamarind fallback configured
• ✅ A clear quality bar — preview for exploration, extended for production designs

Do NOT use this skill when:

• ❌ The user wants an antibody or nanobody → use the boltzgen skill
• ❌ The user wants structure prediction only → use the protenix skill
• ❌ The user wants to score or screen existing designs → use by-scoring / by-screening
• ❌ No target structure exists → predict it with Protenix first
• ❌ The target is membrane-embedded with no soluble construct → restate the problem; PXDesign requires a soluble target

Quick Start

Design a 100-residue binder against chain A of IL6R.cif, preview preset, 10 samples:

# Step 1 — Write config.yaml (see references/yaml-config-spec.md)
cat > /tmp/il6r/config.yaml <<'EOF'
target:
  file: "/data/targets/IL6R.cif"
  chains:
    A: "all"
binder_length: 100
EOF
 
# Step 2 — Run PXDesign on local GPU
PATH=/path/to/conda/envs/protenix/bin:$PATH \
PROTENIX_DATA_ROOT_DIR=$PROTEUS_PROT_DIR/release_data/ccd_cache \
TOOL_WEIGHTS_ROOT=$PROTEUS_PROT_DIR/tool_weights \
CUTLASS_PATH=$HOME/cutlass \
CUDA_HOME=$CUDA_HOME \
pxdesign pipeline \
  --preset preview \
  -i /tmp/il6r/config.yaml \
  --N_sample 10 \
  --dtype bf16 \
  --use_fast_ln True \
  -o /tmp/il6r/output
 
# Step 3 — Parse outputs
python scripts/parse_pxdesign_output.py \
  --output-dir /tmp/il6r/output \
  --out /tmp/il6r/designs.csv

Expected runtime: ~10–20 min on A100 for preview; ~60–120 min for extended. Expected output: summary.csv with 10 rows ranked by ptx_iptm.

Installation

License compliance: All packages permit commercial use in AI applications.

Required environment variables

Hardware

CUDA-capable GPU with bf16 support. Recommended: A100 40GB+ for extended preset. Preview preset fits on 24GB GPUs. Blackwell GPUs (sm_100+, e.g. RTX PRO 6000) must use --use_fast_ln False — the fastfold LayerNorm kernels do not compile for sm_100+.

Compute provider order

1. Local GPU (default in .by/config.json) — fastest iteration, no queue
2. HPC (RunPod) — see the by-deploy-compute skill for setup
3. Tamarind — cloud fallback

Inputs

Required:

• Target structure: .cif (preferred) or .pdb file with absolute path
• Chain IDs must use label_asym_id (PDB-standardized), NOT auth_asym_id
• Parse the CIF before writing the YAML — see Common Issues for the snippet
• Binder length: integer, recommended 60–150 (default 100)

Optional:

• Hotspot residues: integer list per chain (label_seq_id numbering)
• User-supplied "A40, B12" format must be parsed → {A: [40], B: [12]}
• Crop ranges: list of "start-end" strings to limit which residues participate
• MSA directory: precomputed alignment for the target chain
• Preset: preview (fast, exploration) or extended (slow, production)
• `--N_sample`: number of designs to generate (default 10)

See references/yaml-config-spec.md for the full YAML schema.

Outputs

Primary results:

• <output_dir>/design_outputs/<task_name>/summary.csv — ranked design table

Tidy CSV produced by `parse_pxdesign_output.py`:

Design structures: <output_dir>/design_outputs/<task_name>/<name>.cif per design.

See references/filter-thresholds.md for filter definitions and interpretation.

Clarification Questions

⚠️ CRITICAL: ASK THIS FIRST — do not skip Q1.

1. Target structure (ASK THIS FIRST): Do you have a CIF or PDB file for the

target? If not, do you have a UniProt ID or PDB code so we can fetch/predict one first? PXDesign cannot start without a structure.

1. Modality check: Confirm this is a non-antibody binder. If it is an

antibody, nanobody, or VHH, switch to the boltzgen skill before continuing.

1. Epitope / hotspots: Do you know which residues on the target should be

contacted? Provide them in "A40, A50, B12" notation. If unknown, we can start untargeted or use proteus-research to infer hotspots from literature.

1. Binder size: How long should the binder be? Default 100. Smaller targets

or pocket epitopes favor 60–80; large/flat epitopes favor 100–150. See references/de-novo-strategy.md.

1. Quality target: Exploration / feasibility (preview) or production

designs for experimental testing (extended)? Extended is ~5–10× slower.

1. Sample size: How many designs (--N_sample)? Default 10 for preview,

20–50 for extended. Expected pass rate depends on target difficulty — see references/de-novo-strategy.md.

1. Compute provider: Local GPU (default), HPC (RunPod), or Tamarind?

Confirm against .by/config.json. If local, which GPU architecture (Ampere/Hopper/Blackwell)? Blackwell needs --use_fast_ln False.

Standard Workflow

🚨 MANDATORY: USE THE WRITE → BASH → READ PATTERN. DO NOT CALL INTERNAL PYTHON WRAPPERS. 🚨

Pre-flight validation (before first launch)

Run ALL checks before the first pxdesign command. Do not debug one error at a time.

# 1. GPU architecture
GPU_ARCH=$(nvidia-smi --query-gpu=compute_cap --format=csv,noheader | head -1)
echo "GPU arch: sm_${GPU_ARCH/./}"
# If >= 10.0: MUST use --use_fast_ln False
 
# 2. CUDA toolkit
echo "nvcc:  $(which nvcc 2>/dev/null  || echo 'NOT FOUND — set CUDA_HOME')"
echo "ptxas: $(which ptxas 2>/dev/null || echo 'NOT FOUND — add protenix env to PATH')"
 
# 3. CUDA_HOME
echo "CUDA_HOME: ${CUDA_HOME:-NOT SET}"
 
# 4. Chain IDs in target CIF (must match what you write in YAML)
python3 -c "
from Bio.PDB import MMCIFParser
s = MMCIFParser(QUIET=True).get_structure('t', 'TARGET.cif')
for chain in s[0]:
    print(f'  Chain {chain.id}: {len(list(chain.get_residues()))} residues')
"
 
# 5. Confirm each hotspot residue number exists in the target chain

✅ VERIFICATION: All five checks succeed. If ANY check fails, fix it before launching. After one failed launch, switch to BoltzGen protein-anything as a fallback (rare path).

Step 1 — Build the YAML config

Use the helper script (recommended) or write directly:

python scripts/build_config.py \
  --target /data/targets/IL6R.cif \
  --hotspots "A40,A50,A55,B12" \
  --binder-length 80 \
  --preset extended \
  --out /tmp/il6r/config.yaml

✅ VERIFICATION: ✓ Config written: /tmp/il6r/config.yaml (3 chains, 4 hotspots)

The script validates against the schema in references/yaml-config-spec.md before writing. It parses the CIF, confirms each chain exists under label_asym_id, and confirms each hotspot residue number is present.

Step 2 — Run the CLI via Bash

PATH=/path/to/conda/envs/protenix/bin:$PATH \
PROTENIX_DATA_ROOT_DIR=$PROTEUS_PROT_DIR/release_data/ccd_cache \
TOOL_WEIGHTS_ROOT=$PROTEUS_PROT_DIR/tool_weights \
CUTLASS_PATH=$HOME/cutlass \
CUDA_HOME=$CUDA_HOME \
pxdesign pipeline \
  --preset preview \
  -i /tmp/il6r/config.yaml \
  --N_sample 10 \
  --dtype bf16 \
  --use_fast_ln True \
  -o /tmp/il6r/output

✅ VERIFICATION: summary.csv exists at <output_dir>/design_outputs/<task_name>/summary.csv.

Step 3 — Parse the output

python scripts/parse_pxdesign_output.py \
  --output-dir /tmp/il6r/output \
  --out /tmp/il6r/designs.csv

✅ VERIFICATION: ✓ Parsed 10 designs across 1 task batch → /tmp/il6r/designs.csv

The script auto-discovers the summary.csv (handles per-hotspot batching when PXDesign produces multiple task directories) and emits a single tidy CSV.

Step 4 — Inspect & advance

Sort by ptx_iptm desc, then pass designs with ptx_basic_success=True to the by-screening skill for liability and developability checks.

When Scripts Fail

Follow this hierarchy (taken from the BY quality bar):

1. Fix and retry (90%) — missing env var, wrong chain ID, wrong GPU flag.

Re-read the error, fix one thing, re-run. Use the pre-flight checklist.

1. Modify the script (5%) — build_config.py or parse_pxdesign_output.py

has a wrong column name or missed an edge case. Edit it directly.

1. Use as reference (4%) — read the script, adapt the approach inline. Only

when the script's contract does not fit (e.g. PXDesign emits a new column).

1. Write from scratch (1%) — only if PXDesign output format changed

incompatibly. Document why in the campaign log.

Decision Points

Preset selection