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.

2. Modality check: Confirm this is a non-antibody binder. If it is an antibody, nanobody, or VHH, switch to the boltzgen skill before continuing.

3. 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.

4. 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.

5. Quality target: Exploration / feasibility (preview) or production designs for experimental testing (extended)? Extended is ~5–10× slower.

6. 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.

7. 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.
2. 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.
3. 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).
4. Write from scratch (1%) — only if PXDesign output format changed incompatibly. Document why in the campaign log.

Decision Points

Preset selection

Do not send preview results to experimental validation without re-running on extended.

Binder length by target geometry

See references/de-novo-strategy.md for scaffold preset selection and expected pass rates by target difficulty.

Sample size

Set --N_sample based on expected pass rate × desired output count:

• Easy targets (~80% pass rate): --N_sample 10 → ~8 passing
• Standard (~50%): --N_sample 20 → ~10 passing
• Hard (~25%): --N_sample 40 → ~10 passing
• Novel (<15%): --N_sample 80+ and consider re-targeting

Common Issues

Best Practices

1. 🚨 CRITICAL: Run the pre-flight checklist before the first launch. Do not debug one error at a time.
2. 🚨 CRITICAL: Hotspots are integers under the chain key. Strings like "A40" are silently ignored.
3. ✅ REQUIRED: Parse the CIF to confirm label_asym_id chain letters before writing the YAML. PDB auth_asym_id is NOT what PXDesign reads.
4. ✅ REQUIRED: Use absolute paths for target.file and the output directory.
5. ✅ Always specify --dtype bf16 explicitly.
6. ✅ Use preview for exploration; only graduate to extended once the target / hotspot / length combination looks promising.
7. ✅ Sort designs by ptx_iptm descending and gate on ptx_basic_success=True before screening.
8. ✅ When Protenix and AF2 filters disagree, trust Protenix for de novo designs. PXDesign is internally aligned with Protenix.
9. ✨ Optional: Provide a precomputed MSA via chains.<id>.msa if available — improves target representation.
10. ❌ DON'T: Send preview results to experimental validation. Re-run on extended first.
11. ❌ DON'T: Use Tamarind silently if .by/config.json says "local". Report the local failure first.

Suggested Next Steps

After PXDesign returns a parsed designs.csv:

1. Screen all designs with the by-screening skill — runs ipSAE, liability checks, developability filters, and composite ranking. Required before any experimental decision.
2. Refold top-N candidates with the protenix skill for an independent structure validation (multi-seed if possible).
3. Score refolded structures with the by-scoring skill for ipSAE interface quality and composite ranking.
4. Rank & present final candidates via by-display formatting.
5. Lab submission (only when triple-gated approval is in hand) — see the BY campaign workflow in templates/CLAUDE.md.

If no designs pass ptx_basic_success:

• Increase --N_sample
• Switch preview → extended
• Re-tune hotspots (see references/de-novo-strategy.md)
• Adjust binder_length (see Decision Points)
• Add a tighter crop: to focus compute on the epitope region

Related Skills

Upstream (run before):

• by-research — target dossier, epitope identification, prior art search
• protenix — predict a target structure when none is available

Downstream (run after):

• by-screening — ipSAE + liabilities + developability + composite ranking
• by-scoring — interface quality scoring on refolded structures
• by-display — present ranked results to the user

Alternative / complementary:

• boltzgen — antibody / nanobody binder design (use this instead for Ig-fold modalities)
• by-design-workflow — master orchestration when running a full campaign

References

Detailed documentation in this skill:

• references/yaml-config-spec.md — complete YAML schema, validation rules, and the label_asym_id vs auth_asym_id gotcha
• references/filter-thresholds.md — AF2-IG easy/strict, Protenix basic/strict thresholds with PASS/FAIL interpretation
• references/de-novo-strategy.md — hotspot selection strategy, scaffold preset selection (compact/extended/diverse), expected pass rates by target difficulty with the sample sizes that justified those numbers

Scripts:

• scripts/build_config.py — CLI that takes a target CIF + hotspot list + preset and emits a validated PXDesign YAML config
• scripts/parse_pxdesign_output.py — CLI that reads a PXDesign output directory (handles per-hotspot batching) and emits a tidy CSV ranked by ptx_iptm

Related BY skills: boltzgen, protenix, by-scoring, by-screening, by-research, by-design-workflow, by-deploy-compute.

License: All third-party packages used by this skill (Biopython, pandas, PyYAML, CUTLASS) permit commercial use in AI applications.