OneScience-Group/PXDesign

PXDesign

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:

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

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

# 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:

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

Install PXDesign in the current environment:

python -m pip install -e model

Verify the installation:

which pxdesign
pxdesign --help
pxdesign pipeline --help

Environment Variables

After entering the PXDesign root directory, configure the following variables together:

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:

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

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:

weight/release_data/ccd_cache/

To specify another location, set:

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:

PXDesign diffusion checkpoint

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

The recommended location in the reorganized structure is:

weight/release_data/checkpoint/

The required files include:

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:

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

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:

pxdesign --help

To save the results to runs/ as in the examples below, first create the output directory:

mkdir -p runs

Then check the official example YAML:

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

On success, the output should be:

YAML file is valid.

Example Data

The current project provides:

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:

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:

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

2) Parse the Target and Generate Visualization Debug Files

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:

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:

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

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:

PXDesign generation
        -> ProteinMPNN sequence design
        -> AF2-IG filtering

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:

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

Small-Scale Validation

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:

N_sample = 10
N_step = 400

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:

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

@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:

@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:

@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:

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