# 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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nuvolos.com/user-guides/application-specific-guides/pxdesign-and-protenix.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.