# PXDesign and Protenix

[PXDesign](https://github.com/nuvolos-cloud/PXDesign) is a model suite for de novo protein-binder design. It combines a diffusion generator (PXDesign-d) with [Protenix](https://github.com/bytedance/Protenix) and AlphaFold2-IG (AF2-IG) confidence models to score and rank generated binders. Across seven benchmark targets, PXDesign delivers 17–82% nanomolar hits on six.

On Nuvolos, `pxdesign` is pre-installed in a dedicated conda environment along with all required model weights for Protenix and AlphaFold2. No additional installation or weight downloads are needed.

## Quick Start

This guide walks you through a complete binder-design task using the bundled PDL1 demo input.

### Step 1: Open a Terminal and activate the environment

Launch a **Terminal** application on Nuvolos and activate the `pxdesign` conda environment:

```bash
conda activate pxdesign
```

All subsequent commands assume this environment is active.

### Step 2: Prepare the input YAML

Create a YAML file that describes your design task. You can copy the template below, or use the pre-built demo file at `/files/example/PDL1_quick_start.yaml`.

```yaml
target:
  file: "/files/example/5o45.cif"       # Path to the target structure (CIF or PDB)
  chains:
    A:
      crop: ["1-116"]                    # Region of chain A to keep
      hotspots: [40, 99, 107]            # Interface residues that guide diffusion
      msa: "/files/example/msa/PDL1/0"  # Pre-computed MSA directory (recommended)

binder_length: 80                        # Length of the binder to design (residues)
```

> **Tip:** Before running a full job, validate your YAML with:
>
> ```bash
> pxdesign check-input --yaml /files/example/PDL1_quick_start.yaml
> ```

### Step 3: Run the pipeline

Execute the full pipeline in **extended mode** (Protenix + AF2-IG evaluation). The command below runs 10 samples as a quick test:

```bash
pxdesign pipeline \
  --preset extended \
  -i /files/example/PDL1_quick_start.yaml \
  -o /files/example/test_run \
  --N_sample 10 \
  --dtype bf16 \
  --use_fast_ln True \
  --use_deepspeed_evo_attention True
```

| Flag                            | Recommended value                | Notes                                                       |
| ------------------------------- | -------------------------------- | ----------------------------------------------------------- |
| `--preset`                      | `extended`                       | Full pipeline with AF2-IG + Protenix evaluation             |
| `--N_sample`                    | 10 (test) / 10 000+ (production) | More samples → higher chance of finding nanomolar binders   |
| `--dtype`                       | `bf16`                           | Use `fp32` on older GPUs (e.g., V100)                       |
| `--use_fast_ln`                 | `True`                           | Optimized LayerNorm kernels; generally safe to keep enabled |
| `--use_deepspeed_evo_attention` | `True`                           | DeepSpeed Evo attention for Protenix; requires CUTLASS      |

> **First-run notice:** The very first execution performs one-time kernel compilation. Subsequent runs are significantly faster.

### Step 4: Check the results

Results are written to `<out_dir>/design_outputs/<task_name>/`. Open `summary.csv` to see all ranked binder candidates:

```
/files/example/test_run/design_outputs/PDL1_quick_start/
├── summary.csv                  ← Master ranked list with all scores
├── server_xx_mode.png           ← Diagnostic plot showing task difficulty
├── task_info.json               ← Run metadata
├── orig_designed/               ← Raw backbone structures from the diffusion model
├── passing-AF2-IG-easy/         ← Designs passing the AF2-IG-easy filter
└── passing-Protenix-basic/      ← Designs passing the Protenix-basic filter
```

The `summary.csv` contains boolean `*-success` columns for each filter. Use these to quickly select candidates:

| Filter                   | Criteria                              |
| ------------------------ | ------------------------------------- |
| `AF2-IG-easy-success`    | ipAE < 10.85, ipTM > 0.5, pLDDT > 0.8 |
| `AF2-IG-success`         | ipAE < 7.0, pLDDT > 0.9               |
| `Protenix-basic-success` | binder ipTM > 0.8, binder pTM > 0.8   |
| `Protenix-success`       | binder ipTM > 0.85, binder pTM > 0.88 |

## Example files

The `/files/example/` directory contains everything needed to run the PDL1 demo out of the box:

| Path                                   | Description                      |
| -------------------------------------- | -------------------------------- |
| `/files/example/PDL1_quick_start.yaml` | Ready-to-use input configuration |
| `/files/example/5o45.cif`              | PDL1 target structure (mmCIF)    |
| `/files/example/msa/PDL1/0`            | Pre-computed MSA for chain A     |

## Further reference

For detailed documentation on input preparation, running modes, output interpretation, and wet-lab validation workflows, refer to the [PXDesign README on GitHub](https://github.com/nuvolos-cloud/PXDesign?tab=readme-ov-file).