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