/protenix

id: "skill_e18f7e05c7e74168bf07a630d9d6a611"
name: "protenix"
display-name: "Protenix Structure Prediction"
short-description: "Run Protenix v1 (AF3-class, 368M params) structure prediction from a sequence-level JSON spec; emits confidence metrics (ipTM, pTM, pLDDT, ranking_score) for fold validation and complex refolding. Use when predicting a protein or complex structure, validating a designed binder by refolding, or running a multi-seed ensemble to assess prediction stability."
category: "tool"
keywords: "protenix, structure prediction, fold, refold, validation, confidence, ipTM, pTM, pLDDT, multi-seed ensemble, complex prediction, protein-ligand"
version: "1.0"
last-updated: "2026-05-20"

Protenix — Structure Prediction Skill

Protenix v1 is an AF3-class structure prediction model (368M parameters) for proteins, complexes, and protein-ligand systems. This skill wraps the `protenix` CLI with a documented input spec, an input-validating Python entry point, and a multi-seed ensemble aggregator so that callers can drive predictions through scripts instead of ad-hoc bash invocations.

The default compute target is the **local GPU**. HPC (RunPod) is the second choice and Tamarind cloud is the fallback — set the target via `--target` (see scripts).

When to Use This Skill

Use Protenix when you have:

• ✅ **A sequence (or set of sequences) and need a 3D structure** — single chain, complex, homo-oligomer, or protein-ligand.
• ✅ **A designed binder to validate by refolding** — predict the binder + target complex and inspect ipTM / interface pLDDT.
• ✅ **A need for explicit confidence metrics** — ipTM, pTM, pLDDT, ranking_score.
• ✅ **A need for multi-seed ensemble stability** — 3-25 seeds with variance reported.
• ✅ **A protein-ligand complex** — SMILES + protein chain via the `ligand` entity type.
• ✅ **A local GPU available** (CUDA, bf16 capable) or an approved HPC / Tamarind path.

Do NOT use Protenix when:

• ❌ **You need to design a new binder** → use `pxdesign` (de novo binder) or `boltzgen` (antibody / nanobody).
• ❌ **You only need to score an existing prediction** (ipSAE from PAE matrices) → use `by-scoring`.
• ❌ **You need the full liability + developability battery** → use `by-screening`.
• ❌ **You need to fetch sequences from PDB/UniProt** → use `by-database` first, then return here.
• ❌ **You are running on CPU only** → Protenix requires a CUDA-capable GPU; no CPU fallback.
• ❌ **You want pipeline orchestration across research → design → screen** → use `by-design-workflow`.

Quick Start

Local GPU (default). Write an input JSON, then run the wrapper script:

# 1. Write input spec (one prediction object, JSON array form)
cat > /tmp/fold_run/input.json <<'JSON'
[
  {
    "name": "lysozyme_pred",
    "sequences": [
      {"proteinChain": {"sequence": "KVFGRCELAA...", "count": 1}}
    ],
    "modelSeeds": [42],
    "sampleCount": 1
  }
]
JSON

# 2. Run via the wrapper (validates input, invokes local GPU CLI)
python scripts/protenix_fold.py \
  --input /tmp/fold_run/input.json \
  --output-dir /tmp/fold_run/output \
  --model protenix_base_default_v1.0.0 \
  --target local

# 3. Read confidence
ls /tmp/fold_run/output/lysozyme_pred/seed_42/*_summary_confidence_sample_*.json

✅ **VERIFICATION:** Expect `✓ Protenix prediction completed: <output-dir>` on success and at least one `*_summary_confidence_sample_*.json` plus matching `*_sample_*.cif` structure file per seed.

For HPC dispatch, swap `--target local` for `--target hpc` (see `by-deploy-compute` skill for RunPod setup). For Tamarind, use `--target tamarind`.

Installation

| Software | Version | License | Commercial Use | Installation | |----------|---------|---------|----------------|--------------| | Protenix CLI | v1.0 | Apache 2.0 | ✅ Permitted | Install per Protenix repo; expose binary on `PATH` | | Python | ≥ 3.10 | PSF | ✅ Permitted | `pyenv install 3.10` / system package manager | | CUDA toolkit | ≥ 11.8 | NVIDIA EULA | ✅ Permitted (research/commercial per EULA) | Per NVIDIA install guide | | `numpy` | ≥ 1.24 | BSD-3 | ✅ Permitted | `pip install numpy` |

**Environment variables (required for local target):**

| Variable | Value | Notes | |----------|-------|-------| | `PROTEUS_FOLD_DIR` | absolute path to the Protenix install | Owned by the user — do not edit | | `PROTENIX_ROOT_DIR` | `$PROTEUS_FOLD_DIR` | Read by the CLI binary |

**System requirements:**

• CUDA-capable GPU with sufficient VRAM (24 GB+ recommended for `base_*` on complexes > 600 residues).
• bf16 precision required (default `--dtype bf16`).
• HPC/RunPod and Tamarind paths handled by `by-deploy-compute`; this skill only routes to them via `--target`.

**License compliance:** All listed software permits commercial use under the cited licenses.

Inputs

**Required:**

• **Input JSON** — JSON array containing exactly one prediction object:
• `name` (string): identifier for output naming, alphanumeric + underscores.
• `sequences` (array): at least one entity (`proteinChain` or `ligand`).
• `modelSeeds` (array of int): one or more seeds; each generates an independent prediction subdir.
• `sampleCount` (int ≥ 1): diffusion samples per seed.
• See `references/input-json-spec.md` for the full schema, entity types, and edge cases.
• **Output directory** — writable absolute path; the script creates it if missing.

**Optional:**

• **Model name** — defaults to `protenix_base_default_v1.0.0`. See model table below.
• **Compute target** — `local` (default) | `hpc` | `tamarind`.
• **Dtype** — `bf16` (default). Do not change unless you understand the precision/VRAM trade-off.

**Model selection table:**

| Key | Full model name | Use case | |-----|-----------------|----------| | `base_default` | `protenix_base_default_v1.0.0` | **Recommended.** Production predictions, validation. | | `base_20250630` | `protenix_base_20250630_v1.0.0` | Latest checkpoint. Try when `base_default` gives borderline confidence. | | `mini` | `proten