openfold3

# OpenFold3 Structure Prediction

## Prerequisites

| Requirement | Minimum | Recommended |
| ----------- | ------- | ----------- |
| Python      | 3.10+   | 3.11        |
| CUDA        | 12.1+   | 12.4+       |
| GPU VRAM    | 24GB    | 80GB (H100) |
| RAM         | 32GB    | 64GB        |
| Disk (weights) | 3GB  | -           |

## How to run

### Installation

```bash
pip install 'openfold3[cuequivariance]==0.4.1'
```

The default attention kernel is DeepSpeed `DS4Sci_EvoformerAttention`. If
DeepSpeed is unavailable, switch to the cuEquivariance triangle kernels (no
build-from-source) by overriding the eval memory settings in
`model_config.py` (`use_deepspeed_evo_attention: False`,
`use_cueq_triangle_kernels: True`). Some pre-built environments already ship
this override; check before re-patching.

### Weights

Apache-2.0, ~2.3 GB from HF `OpenFold/OpenFold3`. The repo is **gated** (auto-approval) — accept the access form on the HF model page and authenticate (`huggingface-cli login` or `HF_TOKEN`) before downloading:

```bash
export OPENFOLD_CACHE=~/.openfold3
huggingface-cli download OpenFold/OpenFold3 checkpoints/of3-p2-155k.pt \
  --local-dir "$OPENFOLD_CACHE"
```

`run_openfold` will also auto-download to `$OPENFOLD_CACHE` on first run if
egress is open and HF credentials are available (either `HF_TOKEN` or a prior
`huggingface-cli login`) with repo access granted. The interactive
`setup_openfold` helper exists but prompts on stdin; prefer the explicit
download above for non-interactive runs.

### Running

```bash
export OPENFOLD_CACHE=/path/to/cache
run_openfold predict \
  --query_json=queries.json \
  --output-dir out/ \
  --use-msa-server false \
  --use-templates false
```

`run_openfold` discovers the checkpoint under `$OPENFOLD_CACHE` automatically.
Only pass `--inference-ckpt-path <file.pt>` if you have a non-standard layout
or multiple checkpoints and need to pin one explicitly.

For MSA + templates (slower, higher accuracy), drop the two `false` flags. The
MSA server is `api.colabfold.com`; template chain-ID remap hits
`data.rcsb.org` (GraphQL) — both must be reachable.

## Query JSON format

OpenFold3 does **not** read FASTA. Queries are a JSON object validated by
`InferenceQuerySet` (pydantic, `extra: forbid` — unknown keys reject):

```json
{
  "queries": {
    "my_complex": {
      "chains": [
        {"molecule_type": "protein", "chain_ids": ["A"], "sequence": "MQIFVK…"},
        {"molecule_type": "protein", "chain_ids": ["B", "C"], "sequence": "MVLSPA…"},
        {"molecule_type": "ligand",  "chain_ids": ["L"], "smiles": "CC(=O)Oc1ccccc1C(=O)O"}
      ],
      "use_msas": true
    }
  },
  "seeds": [42]
}
```

| `molecule_type` | required field |
| -------- | ---- |
| `protein` / `dna` / `rna` | `sequence` |
| `ligand` | `smiles` **or** `ccd_codes: ["HEM"]` |

`chain_ids` is a list — repeat the same sequence across multiple chain IDs
for homo-oligomers. Per-chain `paired_msa_file_paths` / `main_msa_file_paths`
let you supply your own a3m instead of the server.

## Key parameters

| Flag | Default | Description |
| ---- | ------- | ----------- |
| `--num-diffusion-samples` | 5 | Structures per (query, seed) |
| `--num-model-seeds` | 1 | Number of model seeds per query (multiplies output count alongside JSON `seeds` and diffusion samples) |
| `--use-msa-server` | true | ColabFold MMseqs2 server for MSA |
| `--use-templates` | true | ColabFold template search + RCSB remap |
| `--inference-ckpt-path` | auto-discovered under `$OPENFOLD_CACHE` | Override only — for non-standard layouts or to pin a specific checkpoint file |

## Output format

```
out/
├── summary.txt
├── model_config.json / experiment_config.json
├── inference_query_set.json
└── <query_name>/seed_<N>/
    ├── <query>_seed_<N>_sample_<k>_model.cif
    ├── <query>_seed_<N>_sample_<k>_confidences.json           # full PAE/pLDDT
    ├── <query>_seed_<N>_sample_<k>_confidences_aggregated.json
    └── timing.json
```

`*_confidences_aggregated.json` is the small one to read first:

```json
{
  "avg_plddt": 78.96, "ptm": 0.667, "iptm": 0.0, "gpde": 0.73,
  "has_clash": 0.0, "sample_ranking_score": 0.133,
  "chain_ptm": {"A": 0.667}, "chain_pair_iptm": {}
}
```

## What good output looks like

- `summary.txt` shows `Successful Queries: N` matching your input count
- avg_plddt > 70 (single-seq) / > 80 (with MSA)
- ptm > 0.6; for complexes, iptm > 0.5
- `has_clash: 0.0`
- `.cif` ~50-150 KB per sample for a small protein

## Verify

```bash
grep -E 'Successful|Failed' out/summary.txt
find out -name '*_model.cif' | wc -l   # = queries x json_seeds x num-model-seeds x num-diffusion-samples
```

---

## Troubleshooting

| Error | Cause | Fix |
| ----- | ----- | --- |
| `_deepspeed_evo_attn requires that DeepSpeed be installed` | default eval kernel is DS4Sci on CUDA | install `deepspeed` (needs nvcc + CUTLASS), **or** in `model_config.py` eval block set `use_deepspeed_evo_attention: False` + `use_cueq_triangle_kernels: True` (cuEq path; no build) |
| `CUTLASS_PATH ... not set ... cutlass_library is not installed` | cuEq path still needs the python `cutlass_library` shim | `pip install nvidia-cutlass` |
| `libXrender.so.1: cannot open shared object file` | rdkit (via pdbeccdutils) needs X11 render libs | `apt-get install libxrender1 libxext6 libsm6` |
| `ModuleNotFoundError: boto3` (or `awscrt`) | `openfold3.core.data.io.s3` is eager-imported even when weights are local | `pip install boto3 awscrt` |
| `ValidationError: queries / Field required` or `Input should be an object` | wrong JSON shape | top-level is `{"queries": {"<name>": {...}}}` (a dict, not a list) |
| `ValidationError ... settings / Extra inputs are not permitted` | tried to override model config via `--runner-yaml` | `--runner-yaml` is `InferenceExperimentConfig` only; kernel/memory settings live in `model_config.py` |
| `Failed to fetch chain ID mappings from RCSB for N entries` | `data.rcsb.org` unreachable (allowlist/offline) | run with `--use-temp