openfold3

OpenFold3 Structure Prediction

Prerequisites

How to run

Installation

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:

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

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):

{
  "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]
}

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

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:

{
  "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

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