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 |

Wisp execution

Use python only for bounded interactive checks. For a long or GPU-backed workload, require a selected and probed ssh:<alias> context and load remote-compute-ssh. Put the documented invocation in a self-contained project script, activate the remote environment explicitly, stage only small files with input_paths, and make the command write to a known absolute remote result path. Submit it with run_in_context and register that exact ssh:// path in output_specs. Call monitor_run once when waiting is needed, get_run once for a snapshot, or cancel_run to stop. Do not send a scheduler submission through the SSH-direct runner.

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-templates false, or open egress to data.rcsb.org | | CUDA out of memory | large complex / many samples | reduce --num-diffusion-samples; the low_mem preset (model_setting_presets.yml) offloads more aggressively |