README.md

---
license: apache-2.0
language:
- en
- zh
tags:
- OneScience
- life-science
- protein-design
- protein-binder
- PXDesign
- Protenix
frameworks: PyTorch
---

<p align="center">
  <strong>
    <span style="font-size: 30px;">PXDesign</span>
  </strong>
</p>

# Model Introduction

PXDesign is an open-source suite from the ByteDance team for de novo protein binder design. Given a target protein structure, it generates candidate binders and further filters candidate structures through structure prediction and confidence evaluation workflows.

The complete PXDesign workflow consists of the PXDesign diffusion generation model, ProteinMPNN sequence design, AF2-IG evaluation, and Protenix evaluation. The official implementation provides three primary modes, generation-only, preview, and extended, covering use cases from quick validation to complete candidate screening.

Paper:
> **PXDesign: Fast, Modular, and Accurate De Novo Design of Protein Binders**  
> https://www.biorxiv.org/content/10.1101/2025.08.15.670647v1

# Model Description

The core task of PXDesign is to generate new protein binders from a target protein structure and specified design regions.

The typical workflow is:
```text
Target protein structure and design constraints
  -> PXDesign-d diffusion model
        -> Binder Backbone Generation
  -> ProteinMPNN sequence design
  -> AF2-IG structure prediction and filtering
  -> Protenix structure prediction and filtering (extended mode)
        -> summary.csv
  -> Filtered high-confidence binders
```

Where:
- **PXDesign-d**: Generates candidate binder backbones from the target protein structure, hotspots, binder length, and other conditions.
- **ProteinMPNN**: Designs amino acid sequences for the generated protein backbones.
- **AF2-IG**: Predicts structures and applies quality filters to candidate binder-target complexes.
- **Protenix**: Provides additional structure prediction and confidence evaluation in extended mode.
- **summary.csv**: Summarizes AF2-IG, Protenix, and other evaluation metrics for candidate structures, along with the pass status of each filter.

# Use Cases

| Use case | Description |
| --- | --- |
| De novo protein binder design | Generate new candidate binders from a given target protein structure |
| Interface-guided design | Use hotspots to specify target residues that the binder should preferentially bind |
| Rapid validation of protein design workflows | Use preview mode to quickly evaluate whether the design task and parameters are reasonable |
| High-quality candidate screening | Use extended mode with AF2-IG and Protenix for multistage filtering |
| Structure generation research | Use `pxdesign infer` to run only the PXDesign generation stage |

# Usage

## 1. Using OneCode

Experience intelligent one-click AI4S programming in the OneCode online environment:
[Try intelligent one-click AI4S programming](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 2. Manual Installation and Usage

### Hardware Requirements

- A GPU/DCU is recommended for the PXDesign backbone generation stage; complete inference typically requires substantial GPU memory.
- MSA generation and preparation primarily use the CPU. You can prepare MSAs in advance with `prepare-msa` or by precomputing them.
- The ProteinMPNN, AF2-IG, and Protenix prediction and screening stages depend on deep learning frameworks such as PyTorch and JAX; a GPU/DCU is recommended.
- If GPU/DCU resources are limited, prepare the MSA separately on the CPU first, then run the PXDesign generation, ProteinMPNN, AF2-IG, and Protenix evaluation stages.

### Set Up the Runtime Environment

#### DCU Environment

```bash
# Activate DTK and CONDA first
conda create -n onescience311 python=3.11 -y
conda activate onescience311

# Install with uv support
pip install onescience[bio] -i http://mirrors.onescience.ai:3141/pypi/simple/ --trusted-host mirrors.onescience.ai
```

#### Environment Notes

- If you encounter missing dependencies or version issues during execution, install additional dependencies according to the versions specified in `requirements.txt`.
- Enter the project root and activate the environment:

```bash
cd /path/to/PXDesign-main
conda activate your_env
```

Install PXDesign in the current environment:

```bash
python -m pip install -e model
```

Verify the installation:

```bash
which pxdesign
pxdesign --help
pxdesign pipeline --help
```

### Environment Variables

After entering the PXDesign root directory, configure the following variables together:
```bash
export PXDESIGN_ROOT=$PWD
export TOOL_WEIGHTS_ROOT=$PWD/weight/tool_weights
export PROTENIX_DATA_ROOT_DIR=$PWD/weight/release_data/ccd_cache
```

Check them with:
```bash
echo $PXDESIGN_ROOT
echo $TOOL_WEIGHTS_ROOT
echo $PROTENIX_DATA_ROOT_DIR
```

to confirm the configuration.

## Prepare Weights and Data

The complete PXDesign workflow depends on PXDesign and Protenix model weights, as well as AlphaFold2, ProteinMPNN, and the CCD cache. This model repository already includes the CCD cache and PXDesign/Protenix checkpoints; users only need to prepare the `tool_weights/` portion separately. The complete preparation process is as follows:

### 1) External Tool Weights and CCD Cache

PXDesign provides an official download script:
```bash
bash scripts/download_tool_weights.sh
```

The script uses the official default directories and generates `tool_weights/` and `release_data/ccd_cache/` in the current directory when run directly. This project has been reorganized under a `weight/` directory, so it is recommended to organize or symlink the existing weights and cache to the locations below.

In the current reorganized project structure, place the external tool weights as follows:
```text
weight/
├── tool_weights/
│   ├── af2/        # AlphaFold2 weights
│   └── mpnn/       # ProteinMPNN weights
└── release_data/
    └── ccd_cache/  # Protenix CCD cache
```

- The recommended default location for the CCD cache is:

```text
weight/release_data/ccd_cache/
```

To specify another location, set:

```bash
export PROTENIX_DATA_ROOT_DIR=/path/to/ccd_cache
```

### 2) PXDesign and Protenix Checkpoints

The following model weights are downloaded on demand during the first run, or can be downloaded to the corresponding locations in advance:
```text
PXDesign diffusion checkpoint

Protenix checkpoints:
├── base
├── mini
└── mini_tmpl
```

The recommended location in the reorganized structure is:

```text
weight/release_data/checkpoint/
```

The required files include:
```text
pxdesign_v0.1.0.pt
protenix_base_default_v0.5.0.pt
protenix_mini_default_v0.5.0.pt
protenix_mini_tmpl_v0.5.0.pt
```

### 3) Check the Installation

After preparation is complete, run:
```bash
ls weight/tool_weights/af2/
ls weight/tool_weights/mpnn/
ls weight/release_data/ccd_cache/
ls weight/release_data/checkpoint/*.pt
```
to confirm that the required weights and data are ready.

## 3. Quick Start

### Download the Model Package

```bash
hf download OneScience-Group/PXDesign --local-dir ./PXDesign
cd PXDesign
```

- PXDesign additionally depends on Protenix and PXDesignBench; the corresponding dependency source code is included in this model repository, so separate downloads are not required.
- The complete PXDesign workflow also depends on AlphaFold2, ProteinMPNN, and the CCD cache required by Protenix. Prepare these resources as described in "Prepare Weights and Data" first.

### Quick Verification

First, verify that the command is available:
```bash
pxdesign --help
```

To save the results to `runs/` as in the examples below, first create the output directory:
```bash
mkdir -p runs
```

Then check the official example YAML:
```bash
pxdesign check-input \
  --yaml conf/examples/PDL1_quick_start.yaml
```

On success, the output should be:
```text
YAML file is valid.
```

### Example Data

The current project provides:
```text
conf/examples/
├── PDL1_quick_start.yaml
├── 5o45.cif
└── msa/
    └── PDL1/
        └── 0/
```

`PDL1_quick_start.yaml` defines the PDL1 binder design task.

The typical YAML format is:
```yaml
target:
  file: "./conf/examples/5o45.cif"
  chains:
    A:
      crop: ["1-116"]
      hotspots: [40, 99, 107]
      msa: "./conf/examples/msa/PDL1/0"

binder_length: 80
```

Key fields:
| Field | Description |
| --- | --- |
| `target.file` | Target protein structure file; mmCIF or PDB can be used |
| `target.chains` | Target chains involved in the design |
| `crop` | Residue range retained from the target chain |
| `hotspots` | Target residues used to guide binder interface generation |
| `msa` | Path to the precomputed MSA for the target chain |
| `binder_length` | Amino acid length of the binder to be designed |

PXDesign primarily uses the mmCIF `label_seq_id` as the standard residue index internally. For custom tasks, mmCIF files are recommended, and `parse-target` should be used to check that crop and hotspot specifications point to the intended positions.

### Input Checking and Target Parsing

#### 1) Check the YAML

Run the following before formally executing a design task:

```bash
pxdesign check-input \
  --yaml conf/examples/PDL1_quick_start.yaml
```

#### 2) Parse the Target and Generate Visualization Debug Files
```bash
pxdesign parse-target \
  --yaml conf/examples/PDL1_quick_start.yaml \
  -o runs/debug_target
```

This step is useful for checking the following before running a large-scale design:

- whether the crop is correct;
- whether the hotspots correspond to the intended residues;
- whether the structure chains and residue numbering are correct.

## Inference Examples

PXDesign primarily provides three execution modes:
```text
Generation Only
    -> Generate only the PXDesign binder backbone

Preview Pipeline
    -> PXDesign + ProteinMPNN + AF2-IG

Extended Pipeline
    -> PXDesign + ProteinMPNN + AF2-IG + Protenix
```

### 1. Generation Only: Run PXDesign Generation Only

#### Quick Smoke Test

To first verify that the model, weights, and GPU/DCU work correctly, use a smaller number of steps:
```bash
pxdesign infer \
  -i conf/examples/PDL1_quick_start.yaml \
  -o runs/test_infer \
  --load_checkpoint_dir weight/release_data/checkpoint \
  --N_sample 1 \
  --N_step 20 \
  --dtype bf16 \
  --sample_diffusion_chunk_size 1
```

#### Full-Step Generation Test

```bash
pxdesign infer \
  -i conf/examples/PDL1_quick_start.yaml \
  -o runs/test_infer_full \
  --load_checkpoint_dir weight/release_data/checkpoint \
  --N_sample 10 \
  --N_step 400 \
  --dtype bf16
```

This mode only generates binders and does not provide complete AF2/Protenix filtering results.

### 2. Preview Pipeline

Preview mode runs:
```text
PXDesign generation
        -> ProteinMPNN sequence design
        -> AF2-IG filtering
```

```bash
pxdesign pipeline \
  --preset preview \
  -i conf/examples/PDL1_quick_start.yaml \
  -o runs/test_preview \
  --load_checkpoint_dir weight/release_data/checkpoint \
  --N_sample 2 \
  --N_step 100 \
  --dtype bf16 \
  --use_fast_ln False \
  --use_deepspeed_evo_attention False
```

Preview mode is suitable for:
- initial validation of the complete pipeline;
- checking whether the hotspot/crop settings are reasonable;
- assessing the difficulty of the current design task;
- running a small pilot experiment before a large-scale Extended task.

### 3. Extended Pipeline

Extended mode is the official PXDesign workflow for complete evaluation:

```text
PXDesign generation
        -> ProteinMPNN
        -> AF2-IG
        -> Protenix
        -> summary.csv
```

#### Small-Scale Validation
```bash
pxdesign pipeline \
  --preset extended \
  -i conf/examples/PDL1_quick_start.yaml \
  -o runs/test_extended \
  --load_checkpoint_dir weight/release_data/checkpoint \
  --N_sample 2 \
  --N_step 100 \
  --dtype bf16 \
  --use_fast_ln False \
  --use_deepspeed_evo_attention False
```

#### Quick Start Scale

The official Quick Start example uses:
```text
N_sample = 10
N_step = 400
```

```bash
pxdesign pipeline \
  --preset extended \
  -i conf/examples/PDL1_quick_start.yaml \
  -o runs/test_extended_N10 \
  --load_checkpoint_dir weight/release_data/checkpoint \
  --N_sample 10 \
  --N_step 400 \
  --dtype bf16 \
  --use_fast_ln False \
  --use_deepspeed_evo_attention False
```

## Output Description

The core results from Extended mode are typically located at:
```text
<OUT_DIR>/
└── design_outputs/
    └── <task_name>/
        ├── summary.csv
        ├── task_info.json
        ├── server_extended_mode.png
        ├── orig_designed/
        ├── passing-AF2-IG-easy/
        └── passing-Protenix-basic/
```

If no designs pass the corresponding filters, the `passing-AF2-IG-easy/` or `passing-Protenix-basic/` directories may not be generated. This is normal for small-sample tests.

# Official OneScience Information

| Platform | Main OneScience repository | Skills repository |
| --- | --- | --- |
| Gitee | https://gitee.com/onescience-ai/onescience | https://gitee.com/onescience-ai/oneskills |
| GitHub | https://github.com/onescience-ai/OneScience | https://github.com/onescience-ai/oneskills |


# Citation and License

If you use PXDesign in research, cite the official PXDesign paper:
```bibtex
@article{ren2025pxdesign,
  title={PXDesign: Fast, Modular, and Accurate De Novo Design of Protein Binders},
  author={Ren, Milong and Sun, Jinyuan and Guan, Jiaqi and Liu, Cong and
          Gong, Chengyue and Wang, Yuzhe and Wang, Lan and Cai, Qixu and
          Chen, Xinshi and Xiao, Wenzhi},
  journal={bioRxiv},
  pages={2025--08},
  year={2025},
  publisher={Cold Spring Harbor Laboratory}
}
```

The complete PXDesign pipeline also depends on methods such as Protenix, ProteinMPNN, and AF2-IG. If you use these modules in research, also cite the corresponding original works as described in the official PXDesign README.

Protenix:
```bibtex
@article{bytedance2025protenix,
  title={Protenix - Advancing Structure Prediction Through a Comprehensive AlphaFold3 Reproduction},
  author={ByteDance AML AI4Science Team and Chen, Xinshi and Zhang, Yuxuan
          and Lu, Chan and Ma, Wenzhi and Guan, Jiaqi and Gong, Chengyue
          and Yang, Jincai and Zhang, Hanyu and Zhang, Ke and Wu, Shenghao
          and Zhou, Kuangqi and Yang, Yanping and Liu, Zhenyu and Wang, Lan
          and Shi, Bo and Shi, Shaochen and Xiao, Wenzhi},
  year={2025},
  journal={bioRxiv},
  publisher={Cold Spring Harbor Laboratory},
  doi={10.1101/2025.01.08.631967}
}
```

ProteinMPNN:
```bibtex
@article{dauparas2022robust,
  title={Robust deep learning--based protein sequence design using ProteinMPNN},
  author={Dauparas, Justas and Anishchenko, Ivan and Bennett, Nathaniel
          and Bai, Hua and Ragotte, Robert J and Milles, Lukas and others},
  journal={Science},
  volume={378},
  number={6615},
  pages={49--56},
  year={2022}
}
```

AF2-IG:
```bibtex
@article{bennett2023improving,
  title={Improving de novo protein binder design with deep learning},
  author={Bennett, Nathaniel R and Coventry, Brian and Goreshnik, Inna
          and Huang, Buwei and Allen, Aza and Vafeados, Dionne and others},
  journal={Nature Communications},
  volume={14},
  number={1},
  pages={2625},
  year={2023}
}
```

The official PXDesign repository is released under the **Apache License 2.0**. According to the official README, this license permits academic research and commercial use. Use, modification, and redistribution of the code must comply with the specific terms in this project's `LICENSE`.

In addition:
- AlphaFold2/AF2 weights and related resources are subject to their respective licenses and terms of use.
- ProteinMPNN is subject to the license of its official repository.
- Protenix is subject to the license of its official repository.
- Models and data resources reused through SCNet shared directories remain subject to the authorization conditions of their respective original resources.

For papers, reports, or public releases, also cite PXDesign, Protenix, ProteinMPNN, AF2-IG, and any other third-party models and data resources actually used.