/pxdesign

id: "skill_3242953289f649778bba608ab7bad3e2"
name: "pxdesign"
display-name: "PXDesign Binder Designer"
short-description: "De novo protein binder design using PXDesign — YAML config, CLI invocation, output parsing, and result interpretation for non-antibody binders. Use when designing a non-antibody, non-nanobody protein binder against a target structure."
category: "tool"
keywords: "pxdesign, binder design, de novo, protein design, cli, hotspots, scaffold, preset, preview, extended, ipTM, ipSAE, label_asym_id"
version: "1.0"
last-updated: "2026-05-20"

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

| Software | Version | License | Commercial Use | Installation | |----------|---------|---------|----------------|--------------| | PXDesign binary | as shipped in `$PROTEUS_PROT_DIR` | Internal | ✅ Permitted | Pre-installed by BY environment | | Protenix conda env | matches binary | Apache-2.0 | ✅ Permitted | `conda env create -f $PROTEUS_PROT_DIR/env.yml` | | CUTLASS | ≥3.5 | BSD-3 | ✅ Permitted | `git clone https://github.com/NVIDIA/cutlass.git $HOME/cutlass` | | CUDA toolkit | matches GPU driver | NVIDIA EULA | ✅ Permitted | Bundled with conda env or system CUDA | | Biopython | ≥1.81 | Biopython License (BSD-like) | ✅ Permitted | `pip install biopython` | | pandas | ≥2.0 | BSD-3 | ✅ Permitted | `pip install pandas` | | PyYAML | ≥6.0 | MIT | ✅ Permitted | `pip install pyyaml` |

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

Required environment variables

| Variable | Value | Purpose | |----------|-------|---------| | `PROTENIX_DATA_ROOT_DIR` | `$PROTEUS_PROT_DIR/release_data/ccd_cache` | CCD chemical component cache | | `TOOL_WEIGHTS_ROOT` | `$PROTEUS_PROT_DIR/tool_weights` | PXDesign model weights | | `CUTLASS_PATH` | `$HOME/cutlass` | NVIDIA CUTLASS kernel library | | `CUDA_HOME` | Path to CUDA toolkit (conda env with `nvcc`) | DeepSpeed GPU arch detection | | `PATH` | must include protenix env bin | JAX/XLA needs `ptxas` |

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`:**

| Column | Ty