# AlphaPulldown v2.x

**[Documentation](https://github.com/KosinskiLab/AlphaPulldown/wiki)** | **[Precalculated Input Database](https://github.com/KosinskiLab/AlphaPulldown/wiki/Features-Database)** | **[Downstream Analysis](https://github.com/KosinskiLab/AlphaPulldown/wiki/Downstream-Analysis)**

[AlphaPulldownSnakemake](https://github.com/KosinskiLab/AlphaPulldownSnakemake) provides a convenient way to run AlphaPulldown using a Snakemake pipeline. This lets you focus entirely on **what** you want to compute, rather than **how** to manage dependencies, versioning, and cluster execution. When you deploy the workflow with `snakedeploy`, the configuration file will be copied after deployment to your local project directory as [config/config.yaml](https://github.com/KosinskiLab/AlphaPulldownSnakemake/blob/main/config/config.yaml).

For running without Snakemake, see this [link](https://github.com/KosinskiLab/AlphaPulldown/wiki).

## 1. Installation

Install required dependencies:
```bash
conda env create \
  -n snake \
  -f https://raw.githubusercontent.com/KosinskiLab/AlphaPulldownSnakemake/2.5.0/workflow/envs/alphapulldown.yaml
conda activate snake
```

That's it, you're done!

## 2. Configuration

### Create a Working Directory

Create a new processing directory for your project:

```bash
snakedeploy deploy-workflow \
  https://github.com/KosinskiLab/AlphaPulldownSnakemake \
  AlphaPulldownSnakemake \
  --tag 2.5.0
cd AlphaPulldownSnakemake
```

### Setup Protein Folding Jobs

Create or edit the sample sheet `config/sample_sheet.csv` listing the proteins you want to fold. The simplest format uses one folding specification per line, for example UniProt IDs:

```
P01258+P01579
P01258
P01579
```

Each line represents one folding job:
- `P01258+P01579` - fold these two proteins together as a complex
- `P01258` - fold this protein as a monomer
- `P01579` - fold this protein as a monomer

<details>
<summary>Advanced protein specification options</summary>

You can also specify:
- **FASTA file paths** instead of UniProt IDs: `/path/to/protein.fasta`
- **Specific residue regions**: `Q8I2G6:1-100` (residues 1-100 only)
- **Discontinuous regions**: `Q8I2G6:1-100:150-200` (two separate regions from the same protein)
- **Multiple copies**: `Q8I2G6:2` (dimer of the same protein)
- **Combinations**: `Q8I2G6:2:1-100+Q8I5K4` (dimer of residues 1-100 plus another protein)
- **Copies plus discontinuous regions**: `Q8I2G6:2:1-100:150-200+Q8I5K4`

The same copy/range syntax also works with AlphaFold 3 JSON features. Examples:

- `Q8I2G6_af3_input.json:1-100`
- `Q8I2G6_af3_input.json:1-100:150-200`
- `Q8I2G6_af3_input.json:2:1-100:150-200+Q8I5K4_af3_input.json`

When a workflow or wrapper maps a logical token such as `Q8I2G6:1-100:150-200`
to `Q8I2G6_af3_input.json:1-100:150-200`, AlphaPulldown preserves the region
selection and keeps the AF3 JSON feature input as one discontinuous polymer
chain with preserved residue-number gaps. For the AlphaFold 3 backend this
means chopped regions stay intra-chain, so template contacts between retained
fragments are not masked as inter-chain interactions.
This syntax is parsed by the shared `alphapulldown-input-parser` package used by
both AlphaPulldown and AlphaPulldownSnakemake. For workflow deployments, make
sure the execution environment carries `alphapulldown-input-parser>=0.5.0`.

</details>

### Configure Input Files

Edit `config/config.yaml` and set the path to your sample sheet:

```yaml
input_files:
  - "config/sample_sheet.csv"
```

### Database configuration

Set the path to your AlphaFold databases:

```yaml
databases_directory: "/path/to/alphafold/databases"
```

### Setup Pulldown Experiments

If you want to test which proteins from one group interact with proteins from another group, create a second file such as `config/baits.txt`:

```
Q8I2G6
```

And update your config:

```yaml
input_files:
  - "config/sample_sheet.csv"
  - "config/baits.txt"
```

This will test all combinations: every protein in `config/sample_sheet.csv` paired with every protein in `config/baits.txt`.

<details>
<summary>Multi-file pulldown experiments</summary>

You can extend this logic to create complex multi-partner interaction screens by adding more input files. For example, with three files:

```yaml
input_files:
  - "proteins_A.txt"  # 5 proteins
  - "proteins_B.txt"  # 3 proteins
  - "proteins_C.txt"  # 2 proteins
```

This will generate all possible combinations across the three groups, creating 5×3×2 = 30 different folding jobs. Each job will contain one protein from each file, allowing you to systematically explore higher-order protein complex formation.

**Note**: The number of combinations grows multiplicatively, so be mindful of computational costs with many files.

</details>

## 3. Execution

Run the pipeline locally:

```bash
snakemake --profile config/profiles/desktop --cores 8
```

<details>
<summary>Cluster execution</summary>

For running on a SLURM cluster, first create a virtual terminal e.g. using `screen`:

```bash
screen -S snakemake_session
```
Then activate your conda/mamba environment:
```bash
mamba activate snake
```
Finally, use the slurm executor plugin:
```bash
snakemake \
  --executor slurm \
  --profile config/profiles/slurm \
  --jobs 200 \
  --restart-times 5
```

Detach with `Ctrl + A` then `D`. Reattach later with `screen -r snakemake_session`.

Job specific logs are created automatically and stored in your `AlphaPulldownSnakemake/slurm_logs` directory.

</details>

## 4. Results

After completion, you'll find:
- **Predicted structures** in PDB/CIF format in the output directory
- **Per-fold interface scores** in `output/predictions/<fold>/interfaces.csv`
- **Aggregated interface summary** in `output/reports/all_interfaces.csv` when `generate_recursive_report: true`
- **Interactive APLit web viewer (recommended)** for browsing all jobs, PAE plots and AlphaJudge scores
- **Optional Jupyter notebook** with 3D visualizations and quality plots
- **Results table** with confidence scores and interaction metrics

# Recommended: explore results with APLit

[APLit](https://github.com/KosinskiLab/aplit)
 is a Streamlit-based UI for browsing AlphaPulldown runs (AF2 and AF3) and AlphaJudge metrics.

Install APLit (once):
```bash
pip install git+https://github.com/KosinskiLab/aplit.git
```

Then launch it from your project directory, pointing it to the predictions folder:
```bash
aplit --directory output/predictions
```

This starts a local web server (by default at `http://localhost:8501`) where you can:

- Filter and sort jobs by ipTM, PAE or AlphaJudge scores

- Inspect individual models in 3D (3Dmol.js)

- View PAE heatmaps and download structures / JSON files

On a cluster, run aplit on the login node and forward the port via SSH:
```bash
# on cluster
aplit --directory /path/to/project/output/predictions --no-browser
```
```bash
# on your laptop
ssh -N -L 8501:localhost:8501 user@cluster.example.org
```

Then open `http://localhost:8501` in your browser.



---

## Advanced Configuration

### SLURM defaults for structure inference
Override default values to match your cluster:

```yaml
slurm_partition: "gpu"                      # which partition/queue to submit to
slurm_qos: "normal"                         # optional QoS if your site uses it
structure_inference_gpus_per_task: 1        # number of GPUs each inference job needs
structure_inference_gpu_model: "3090"       # optional GPU model constraint (remove to allow any)
structure_inference_tasks_per_gpu: 0        # <=0 keeps --ntasks-per-gpu unset in the plugin
slurm_exclude_nodes: ""                     # optional comma-separated nodes to avoid (sbatch --exclude)
structure_inference_max_runtime: 10080      # cap wall time (min) at the partition MaxTime
```

`structure_inference_gpus_per_task` and `structure_inference_gpu_model` are read by the
Snakemake Slurm executor plugin and translated into `--gpus=<model>:<count>` (or `--gpus=<count>` if
no model is specified). We no longer use `slurm_gres`; requesting GPUs exclusively through these
fields keeps the job submission consistent across clusters.

`structure_inference_tasks_per_gpu` toggles whether the plugin also emits `--ntasks-per-gpu`. Leaving
the default `0` prevents that flag, which avoids conflicting with the Tres-per-task request on many
systems. Set it to a positive integer only if your site explicitly requires `--ntasks-per-gpu`.

The remaining optional fields help with two common cluster issues: keeping inference off GPUs it
can't use, and large complexes running out of GPU memory. Defaults are sensible; expand below only if
you hit these.

<details>
<summary>Avoiding unsuitable GPUs (<code>slurm_exclude_nodes</code>, <code>gpu_model</code>) and the runtime cap</summary>

- **Restrict to one model** with `structure_inference_gpu_model` (e.g. `"A100"`) → the plugin emits
  `--gpus=<model>:<count>`. Accepts a single model name; leave `""` for any.
- **Exclude specific nodes** with `slurm_exclude_nodes` → passed verbatim to `sbatch --exclude`
  (e.g. `"gpu50,gpu51"`). Use it for nodes whose GPU the container can't use — e.g. a CUDA compute
  capability newer than the container's bundled `ptxas` (fails `ptxas too old` / `UNIMPLEMENTED`).
  `--exclude` is allowed in `slurm_extra` whereas `--constraint`/`--gres`/`--gpus` are not, so it is
  the supported way to drop a few nodes while keeping the rest of the partition.
- **`structure_inference_max_runtime`** caps per-job wall time (minutes). Wall time scales as
  `1440 * attempt`, so without a cap enough retries exceed the partition `MaxTime` and SLURM rejects
  the job with `Requested time limit is invalid`. Set it to your partition's `MaxTime`
  (`scontrol show partition <name>`); default 7 days (10080).

</details>

<details>
<summary>Unified memory for large complexes (<code>structure_inference_unified_memory</code>)</summary>

Large AlphaFold 3 inputs (or smaller-VRAM GPUs) can fail with `RESOURCE_EXHAUSTED` /
`Allocator (GPU_0_bfc) ran out of memory`. Inference enables JAX/XLA **unified (managed) memory** by
default so the model spills from GPU VRAM into host RAM instead of OOM-ing (slower while spilling, but
it completes) — the
[DeepMind-recommended setting](https://github.com/google-deepmind/alphafold3/blob/main/docs/performance.md)
for large inputs. It is exported inside the prediction container as:

```sh
export TF_FORCE_UNIFIED_MEMORY=true
export XLA_PYTHON_CLIENT_PREALLOCATE=false   # don't grab a huge VRAM chunk up front
export XLA_CLIENT_MEM_FRACTION=$FRACTION      # how far past physical VRAM XLA may allocate
export XLA_PYTHON_CLIENT_MEM_FRACTION=$FRACTION
```

`XLA_PYTHON_CLIENT_PREALLOCATE=false` is required: without it XLA reserves a large
slice of VRAM immediately, which defeats the point of letting the allocator grow into
host RAM on demand.

```yaml
structure_inference_unified_memory: true     # set false to fail fast on OOM instead
structure_inference_xla_mem_fraction: auto   # "auto", or pin a number like 3.2
```

With the default `structure_inference_xla_mem_fraction: auto`, the fraction is computed
**per job at run time** as `(allocated host RAM) / (physical GPU VRAM)`: the GPU VRAM is
read with `nvidia-smi` once the job lands on a node, and the host RAM is the job's SLURM
`--mem` allocation (which scales with retry attempts). This keeps the unified-memory
ceiling within the SLURM allocation so XLA cannot oversubscribe host RAM beyond what the
job requested — which would otherwise get the job OOM-killed. The chosen fraction is
logged as a `[unified-memory]` line at the top of the job log. Pin a number instead if
you want a fixed multiplier regardless of GPU/RAM (mirrors the EMBL `run_AF_multimer.sh`
convention).

> The fraction is computed in the job shell rather than via the SLURM executor: the
> executor passes the submit environment through with `--export=ALL` but offers no
> per-job env hook, and the value depends on which GPU the job lands on (only known at
> run time). Computing it in the container shell also avoids the apptainer env-crossing
> that submit-side env vars would need.

Because spilling is slower, make sure the job also requests enough host RAM
(`structure_inference_ram_bytes`, in MB) to hold the overflow — under `auto` that RAM is
exactly what the fraction is sized against.

</details>

### Using Precomputed Features

If you have precomputed protein features, specify the directory:

```yaml
feature_directory:
  - "/path/to/directory/with/features/"
```

> **Note**: If your features are compressed, set `compress-features: True` in the config.

### Feature generation flags (`create_individual_features.py`)

You can tweak the feature-generation step by editing `create_feature_arguments` (or by running the
script manually). Commonly used flags:

- `--data_pipeline {alphafold2,alphafold3}` – choose the feature format to emit.
- `--db_preset {full_dbs,reduced_dbs}` – switch between the full BFD stack or the reduced databases.
- `--use_mmseqs2` – rely on the remote MMseqs2 API; skips local jackhmmer/HHsearch database lookups.
- `--skip_msa` – generate query-only single-sequence features instead of running bulk MSA searches. Use these feature pickles with `run_structure_prediction.py --pair_msa=False`.
- `--use_precomputed_msas` / `--save_msa_files` – reuse stored MSAs or keep new ones for later runs.
- `--compress_features` – zip the generated `*.pkl` files (`.xz` extension) to save space.
- `--skip_existing` – leave existing feature files untouched (safe for reruns).
- `--seq_index N` – only process the N‑th sequence from the FASTA list.
- `--use_hhsearch`, `--re_search_templates_mmseqs2` – toggle template search implementations.


### Structure analysis & reporting

Post-inference analysis is enabled by default. You can disable it or add a project-wide summary in `config/config.yaml`:

```yaml
enable_structure_analysis: true             # skip alphaJudge if set to false
generate_recursive_report: true             # disable if you do not need all_interfaces.csv
recursive_report_arguments:                 # optional extra CLI flags for alphajudge
  --models_to_analyse: best
```


### Changing Folding Backends

To use AlphaFold3 or other backends:

```yaml
structure_inference_arguments:
  --fold_backend: alphafold3
  --<other-flags>
```

> **Note**: AlphaPulldown supports: `alphafold2`, `alphafold3`, `alphalink`, and `unifold` backends.

### Backend Specific Flags

<details>
<summary>AlphaFold2 Flags</summary>

```yaml
# Whether the result pickles are going to be zipped (.xz).
  --compress_result_pickles: False

# Whether the result pickles are going to be removed.
  --remove_result_pickles: False

# The models to run the final relaxation step on. If `all`, all models are relaxed, which may be time consuming. If `best`, only the most confident model is relaxed. If `none`, relaxation is not run. Turning off relaxation might result in predictions with distracting stereochemical violations but might help in case you are having issues with the relaxation stage.
  --models_to_relax: None

# Whether to remove aligned_confidence_probs, distogram and masked_msa from pickles.
  --remove_keys_from_pickles: True

# Whether to convert predicted pdb files to modelcif format.
  --convert_to_modelcif: True

# Whether to allow resuming predictions from previous runs or start anew.
  --allow_resume: True

# Number of recycles
  --num_cycle: 3

# Number of predictions per model
  --num_predictions_per_model: 1

# Whether to pair the MSAs when constructing multimer objects.
  --pair_msa: True

# Whether to save features for multimeric object.
  --save_features_for_multimeric_object: False

# Do not use template features when modelling.
  --skip_templates: False

# Run predictions for each model with logarithmically distributed MSA depth.
  --msa_depth_scan: False

# Whether to use multimeric templates.
  --multimeric_template: False

# A list of names of models to use, e.g. model_2_multimer_v3 (default: all models).
  --model_names: None

# Number of sequences to use from the MSA (by default is taken from AF model config).
  --msa_depth: None

# Path to the text file with multimeric template instruction.
  --description_file: None

# Path to directory with multimeric template mmCIF files.
  --path_to_mmt: None

# A desired number of residues to pad.
  --desired_num_res: None

# A desired number of msa to pad.
  --desired_num_msa: None

# Run multiple JAX model evaluations to obtain a timing that excludes the compilation time, which should be more indicative of the time required for inferencing many proteins.
  --benchmark: False

# Choose preset model configuration - the monomer model, the monomer model with extra ensembling, monomer model with pTM head, or multimer model.
  --model_preset: monomer

# Change output directory to include a description of the fold as seen in previous alphapulldown versions
  --use_ap_style: False

# Whether to run Amber relaxation on GPU.
  --use_gpu_relax: True

# Whether to use dropout when inferring for more diverse predictions.
  --dropout: False

```
</details>

<details>
<summary>AlphaFold3 Flags</summary>

```yaml

# Path to a directory for the JAX compilation cache.
  --jax_compilation_cache_dir: None

# Strictly increasing order of token sizes for which to cache compilations. For any input with more tokens than the largest bucket size, a new bucket is created for exactly that number of tokens.
  --buckets: ['64', '128', '256', '512', '768', '1024', '1280', '1536', '2048', '2560', '3072', '3584', '4096', '4608', '5120']

# Flash attention implementation to use. 'triton' and 'cudnn' uses a Triton and cuDNN flash attention implementation, respectively. The Triton kernel is fastest and has been tested more thoroughly. The Triton and cuDNN kernels require Ampere GPUs or later. 'xla' uses an XLA attention implementation (no flash attention) and is portable across GPU devices.
  --flash_attention_implementation: triton

# Number of diffusion samples to generate.
  --num_diffusion_samples: 5 

# Number of seeds to use for inference. If set, only a single seed must be provided in the input JSON. AlphaFold 3 will then generate random seeds in sequence, starting from the single seed specified in the input JSON. The full input JSON produced by AlphaFold 3 will include the generated random seeds. If not set, AlphaFold 3 will use the seeds as provided in the input JSON.
  --num_seeds: None

# If set, save generated template mmCIFs to templates_debug/ during AF3 input prep.
  --debug_templates: False

# If set, dump featurised MSA arrays and final complex A3M before inference.
  --debug_msas: False

# Number of recycles to use during AF3 inference.
  --num_recycles: 10

# Whether to save final trunk single/pair embeddings in AF3 output.
  --save_embeddings: False

# Whether to save final distogram in AF3 output.
  --save_distogram: False
```

When you provide multiple residue ranges for one AF3 input, AlphaPulldown slices
the sequence, MSA, and template columns to the requested residues and preserves
the result as one discontinuous AF3 polymer chain with gapped residue numbering.
The original residue IDs are written to the mmCIF author-numbering fields
(`auth_seq_id` and `pdbx_PDB_ins_code`); overlapping IDs are disambiguated with
insertion codes such as `2A`, `2B`, and so on.
For the AlphaFold 3 backend this keeps retained fragments intra-chain, so
template contacts between those fragments are not masked as inter-chain
interactions.

</details>

***

## How to Cite

If AlphaPulldown contributed significantly to your research, please cite [the corresponding publication](https://doi.org/10.1093/bioinformatics/btaf115) in *Bioinformatics*:

```bibtex
@article{Molodenskiy2025AlphaPulldown2,
  author    = {Molodenskiy, Dmitry and Maurer, Valentin J. and Yu, Dingquan and Chojnowski, Grzegorz and Bienert, Stefan and Tauriello, Gerardo and Gilep, Konstantin and Schwede, Torsten and Kosinski, Jan},
  title     = {AlphaPulldown2—a general pipeline for high-throughput structural modeling},
  journal   = {Bioinformatics},
  volume    = {41},
  number    = {3},
  pages     = {btaf115},
  year      = {2025},
  doi       = {10.1093/bioinformatics/btaf115}
}
```