OpenFold3 Inference¶

Welcome to the Documentation for running inference with OpenFold3, our fully open source, trainable, PyTorch-based reproduction of DeepMind’s AlphaFold3. OpenFold3 implements the features described in AlphaFold3 Nature paper.

This guide covers how to use OpenFold3 to make structure predictions.

1. Inference features¶

OpenFold3 replicates the full set of input features described in the AlphaFold3 publication. All features of AlphaFold3 are fully implemented and supported in training. We are actively working on integrating the same functionalities into the inference pipeline.

Below is the current status of inference feature support by molecule type:

1.1 Protein¶

Supported:

Prediction with MSA
- using ColabFold MSA pipeline
- using pre-computed MSAs
Prediction without MSA
OpenFold3’s own MSA generation pipeline
Template-based prediction
- using ColabFold template alignments
- using pre-computed template alignments
Non-canonical residues

Coming soon:

Covalently modified residues and other cross-chain covalent bonds
User-specified template structures (as opposed to top 4)

1.2 DNA¶

Supported:

Prediction without MSA (per AF3 default)
Non-canonical residues

Coming soon:

Covalently modified residues and other cross-chain covalent bonds

1.3 RNA¶

Supported:

Prediction with MSA, using OpenFold3’s own MSA generation pipeline
Prediction without MSA
OpenFold3’s own MSA generation pipeline
Non-canonical residues

Coming soon:

Template-based prediction
Covalently modified residues and other cross-chain covalent bonds
Protein-RNA MSA pairing

1.4 Ligand¶

Supported:

Non-covalent ligands

Coming soon:

Covalently bound ligands
Polymeric ligands such as glycans

2. Pre-requisites¶

OpenFold3 Conda Environment. See OpenFold3 Installation for instructions on how to build this environment.
OpenFold3 Model Parameters. See OpenFold3 Setup for an easy option to download model parameters.

3. Running OpenFold3 Inference¶

A prediction job can be submitted with the following command:

run_openfold --query-json=<query_json>

Sample input query jsons can be found in the examples/example_inference_inputs directory.

Full output directories are provided on the OpenFold HuggingFace repo. These include:

Single-chain protein (monomer) – Ubiquitin (PDB: 1UBQ)
Multi-chain protein with identical chains (homomer) – GCN4 leucine zipper (PDB: 2ZTA)
Multi-chain protein with different chains (multimer) – Deoxy human hemoglobin (PDB: 1A3N)
Protein-ligand complex – Mcl-1 with small molecule inhibitor (PDB: 5FDR)

3.1 Input Data: Query JSON¶

Queries can include any combination of single- or multi-chain proteins, with or without ligands, and may contain multiple such complexes.
Input is provided via a query.json file — a structured JSON document that defines each query, its constituent chains, chain types (e.g., protein, DNA, ligand) and sequences or molecular graphs. Optionally, the query can include paths to precomputed protein or RNA MSAs.
See OpenFold3 input format for instructions on how to specify your input data.

3.2 Inference Modes by MSA Input¶

OpenFold3 currently supports three inference modes with respect to MSAs:

🚀 With ColabFold MSA Server (default)
📂 With Precomputed MSAs
🚫 Without MSAs (MSA-free)

Each mode shares the same command structure but differs in how MSAs are provided or generated.

3.2.1 🚀 Inference with ColabFold MSA Server (Default)¶

This mode automatically generates MSAs using the ColabFold server. Only protein sequences are sent to the server. We recommend this mode if you only have a couple of structures to predict.

run_openfold predict \
    --query-json /path/to/query.json \
    --use-msa-server \
    --output-dir /path/to/output/

This command uses the run_openfold binary, for which the source code is available here.

Required arguments

--query-json (Path)
- Path to the input query JSON file.

Optional arguments

--inference-ckpt-path (Path, optional)
- Path to a model checkpoint file (.pt file)
- Will use a default checkpoint if not specified, which will be downloaded on the first inference run. See OpenFold3 Parameters for details
--inference-ckpt-name (str, optional, default = openfold3_p2_v1)
- Name of model checkpoint from a supported list to be used for inference. Only used if inference_ckpt_path is None. See {OpenFold3 Parameters for information
--use-msa-server (bool, optional, default = True)
- Whether to use the ColabFold server for MSA generation.
--output-dir (Path, optional, default = test_train_output/)
- Directory where outputs will be written.
--num-diffusion-samples (int, optional, default = 5)
- Number of diffusion samples per query.
--num-model-seeds (int, optional, default = 1)
- Number of random seeds to use per query.
- To manually select specific seeds, please use the runner.yml and refer to the Custom Random Seeds section below.
--runner-yaml (Path, optional, default = null)
- YAML config for full control over model and data parameters. See the configuration reference and full configuration reference file for all available options.
- See the runner yaml section below for more information

📝 Notes:

Only protein sequences are submitted to the ColabFold server so this mode only uses MSAs for protein chains.
All arguments can also be set via runner_yaml, but command-line flags take precedence and will override values specified in the YAML file (see Customized Inference Settings for details).

3.2.2 📂 Inference with Precomputed MSAs¶

This mode allows inference using MSA files prepared manually or by external tools. We recommend this mode for high-throughput screeing applications where you want to run hundreds or thousands of predictions. See the precomputed MSA documentation for a step-by-step tutorial, the MSA generation guide for using our MSA generation pipeline and the precomputed MSA explanatory document for a more in-depth explanation on how precomputed MSA handling works.

An example query json with a sample of how the alignment directories can be formatted is available here

run_openfold predict \
    --query-json /path/to/query_precomputed.json \
    --use-msa-server=False \
    --output-dir /path/to/output/ \
    --runner-yaml /path/to/inference_precomputed.yml

3.2.3 🚫 Inference Without MSAs¶

You can run OpenFold3 without MSAs. Prediction performance may be worse than predictions that use MSAs

run_openfold predict \
    --query-json /path/to/query.json \
    --use-msa-server=False \
    --output-dir /path/to/output/ \
    --runner-yaml /path/to/inference.yml

3.3 Customized Inference Settings Using `runner.yml`¶

OpenFold3 provides extensive customization options through a runner.yml configuration file. This file allows you to override the default settings defined in validator.py and customize the inference behavior to your needs.

We provide several example runner files in our examples directory that demonstrate common use cases like:

Running on multiple GPUs
Using low memory settings
Customizing output formats
Enabling cuEquivariance kernels
Enabling AMD ROCm Triton kernels
Saving MSA and Template processing outputs
And more

For a complete reference of all available configuration options:

See our full configuration example with all possible settings
Read the detailed configuration reference documentation that explains each setting

Important Note on Model Parameter Customization:

The default settings of the model are defined in openfold3/projects/of3_all_atom/config/model_config.py

The model parameters section of the configuration may by passing an update in the runner.yml under the custom field in model_update. See the cuequivariance.yml example for one such update.

Note that CLI arguments take precedence over configuration file settings.

Below we’ll walk through some of the most common configuration scenarios and how to implement them:

🖥️ Run on Multiple GPUs or Nodes¶

The inference pipeline (as well as training) is backed by Pytorch Lightning, which allows us to automatically distribute large batch jobs of multiple predictions across all available GPUs and nodes. To enable distributed inference, specify the hardware configuration under pl_trainer_args in your runner.yml:

pl_trainer_args:
  devices: 4      # Default: 1
  num_nodes: 1    # Default: 1

🌱 Change the random seeds for the model¶

By default, only 1 random model seed is used with 5 diffusion samples, in which case, one inference run will be performed, yielding 5 output structures using the same seed.

Given n queries, m seeds and l diffusion samples, the model will perform n × m independent forward passes and produce n × m × l predicted structures.

A custom list of random seeds can be provided to the runner.yml under experiment_settings in the following format

experiment_settings:
  seeds:
    - 100
    - 101
    - ... 

Seeding behavior is controlled in the following priority:

Command line argument --num-model-seeds
runner.yml via the experiment_settings.seeds field.

📦 Output in PDB Format¶

Change the structure output format from cif to pdb using output_writer_settings:

output_writer_settings:
  structure_format: pdb    # Default: cif

📦 Output single and pair model embeddings¶

To save model embeddings, add the field write_latent_outputs to the output_writer_settings i.e.:

output_writer_settings:
  write_latent_outputs: True

⏩ Skip full confidence model outputs¶

OpenFold3 writes both aggregated confidence scores and full, per-atom confidence scores. See Prediction Outputs for more information.

For large inference jobs, especially jobs with many seeds, it is useful to skip the full confidence score generation to save disk space. This can be done with the following settings

output_writer_settings:
  write_full_confidence_scores: False 

🧠 Low Memory Mode¶

To run inference on larger queries to run on limited memory, add the following to apply the model presets to run in low memory mode.

Note: These settings cause the pairformer embedding output from the diffusion samples to be computed sequentially. Significant slowdowns may occur, especially for large number of diffusion samples.

model_update:
  presets:
    - predict  # required for inference
    - low_mem

🔴 AMD ROCm Inference with Triton Kernels¶

On AMD GPUs, OpenFold3 can use native Triton kernels for the Evoformer attention and TriangleMultiplicativeUpdate layers instead of the default CUDA-specific kernels.

First, install PyTorch for ROCm and openfold3 (see Installation). Then enable the Triton kernels in your runner.yml using the provided triton.yml example:

model_update:
  presets:
    - predict
  custom:
    settings:
      memory:
        eval:
          use_triton_triangle_kernels: true
          use_deepspeed_evo_attention: false
          use_cueq_triangle_kernels: false

run_openfold predict \
    --query-json /path/to/query.json \
    --output-dir /path/to/output/ \
    --runner-yaml examples/example_runner_yamls/triton.yml

Note on first-run compilation: Triton JIT-compiles kernels on first use and caches them to ~/.triton/cache. The compilation is a one-time cost per unique sequence length per machine; subsequent runs at the same length incur no overhead.

3.4 Customized ColabFold MSA Server Settings Using `runner.yml`¶

All settings for the ColabFold server and outputs can be set under msa_computation_settings

Saving MSA outputs¶

By default, MSA outputs are written to a temporary directory and are deleted after prediction is complete.

These settings can be saved by changing the following fields:

msa_computation_settings:
  msa_output_directory: <custom path>
  cleanup_msa_dir: False  # If False, msa paths will not be deleted between runs 
  save_mappings: True 

template_preprocessor_settings:
  output_directory: <custom path> 

MSAs per chain are saved using a file / directory name that is the hash of the sequence. Mappings between the chain name, sequence, and representative ids can be saved via the save_mappings field.

Use a Privately Hosted ColabFold MSA Server¶

Specify the URL of your private MSA server with the server_url field:

msa_computation_settings:
  server_url: https://my.private.colabfold.server

Save MSAs in A3M Format¶

Choose the file format for saving MSAs retrieved from ColabFold:

msa_computation_settings:
  msa_file_format: a3m     # Options: a3m, npz (default: npz)

4. Model Outputs¶

In the inference pipeline, we generate a dedicated output directory for each query, named by the corresponding query key (e.g., query_1 or 3hfm, if the PDB ID is provided). Each such directory will contain prediction results, MSAs, and intermediate files for MSA and template processing:

4.1 Prediction Outputs (`query/seed/`)¶

Each seed produces l (number of diffusion samples) structure predictions, and their associated confidence scores, stored in subdirectories named after the query, seed and the index of the diffusion sample, e.g.:

<output_directory>
 ├── query_1
	 └── seed_42
        ├── query_1_seed_42_sample_1_model.cif
        ├── query_1_seed_42_sample_1_confidences.json
        ├── query_1_seed_42_sample_1_confidences_aggregated.json
        └── timing.json 

*_model.cif (or .pdb): Final predicted 3D structure (with per-atom pLDDT in B-factor if .pdb).
*_confidences.json: Per-atom confidence scores:
- plddt: Predicted Local Distance Difference Test
- pae: Predicted Aligned Error
- pde: Predicted Distance Error
*_confidences_aggregated.json: Aggregated metric:
- avg_plddt - Average pLDDT over structure
- gpde - Global Predicted Distance Error (see AF3 SI Section 5.7 Eq. 16)
- ptm - Predicted TM score of a full complex (SI §5.9.1)
- iptm - Interface variant of a predicted TM score of a full complex (SI §5.9.1)
- disorder - Average relative solvent accessible surface area (RASA) over all protein atoms (§5.9.3, item 1)
- has_clash - Whether any pair of polymer chains has steric clashes (0.0 if no clashes, 1.0 otherwise)
- sample_ranking_score - Weighted sum of ptm, iptm, disorder, has_clash. Used to rank predictions (SI §5.9.3, item 1)
- chain_ptm - Per-chain predicted TM score (SI §5.9.1)
- chain_pair_iptm - Interface variant of predicted TM score of each chain pairs (SI §5.9.1, §5.9.3, item 3)
- bespoke_iptm - Average chain_pair_iptm between each chain of a pair and all other chains. Used to rank interface predictions (SI § 5.9.3, item 3)
timing.json: The runtime for the submitted query (s), not including the runtime for any MSA computations.

4.2 Processed MSAs (`main/` and `paired/`)¶

Only created if --use-msa-server=True.
Processed MSAs for each unique chain are saved as .npz files used to create input features for OpenFold3. If a chain is reused across multiple queries, its MSA is only computed once and named after the first occurrence. This reduces the number of queries to the ColabFold server.

For a sequence with two representative chains, the final output directory would have this format:

<msa_output_directory>
├── main
│   ├── <hash of sequence A>.npz
│   └── <hash of sequence B>.npz
├── mappings
│   ├── chain_id_to_rep_id.json
│   ├── query_name_to_complex_id.json
│   ├── README.md
│   ├── rep_id_to_seq.json  # hash to sequence mapping
│   └── seq_to_rep_id.json
└── paired
    └── <hash of concatenation of sequences A and B>
        ├── <hash of sequence A>.npz
        └── <hash of sequence B>.npz

If a query is a heteromeric protein complex (has at least two different protein chains) and --use-msa-server is enabled, paired MSAs are also generated. If a set of chains with a specific stoichiometry is reused across multiple queries, for example if the same heterodimer is screened against multiple small molecule ligands, its set of paired MSAs is only computed once and named after the first occurrence. This reduces the number of queries to the ColabFold server.

<msa_output_directory>
 ├── paired
    └── <hash of concatenation of sequences A and B> 
        ├── <hash of sequence A>.npz
        └── <hash of sequence B>.npz

In summary, we submit a total of 1 + n queries to the ColabFold MSA server per run - one query for the set of all unqiue protein sequences in the inference query json file (unpaired/main MSAs) and n additional queries for the collection of unqiue protein chain combinations for heteromeric complexes (paired MSAs).

The MSA deduplication behavior is also present for precomputed MSAs. See the chain deduplication utility section for details.

Note: The raw ColabFold MSA .a3m alignment files and scripts are saved to <msa_output_directory>/raw/.
This directory is then deleted upon completion of MSA processing by the OpenFold3 workflow to avoid disruption to future inference submissions.

To manually keep the raw ColabFold outputs, remove this line here here.

4.3 Mapping outputs (`mapping/`)¶

If the same msa_output_directory is used between runs, the rep_id_to_seq.json and seq_to_rep_id.json mappings are updated with the new sequences, while the other mappings are overwritten.

<msa_output_directory>
 ├── paired
    └── <hash of concatenation of sequences A and B> 
        ├── <hash of sequence A>.npz
        └── <hash of sequence B>.npz

4.4 Query Metadata¶

There are several system-generated files that record the state of submitted inference job.

Inference Query Set – Input query and references to auxiliary files (e.g. MSA alignments and template files)
Model Config - Model settings, e.g. architecture and memory settings
Experiment Config – Experiment settings for the inference run

4.4.1 Inference Query Set (`inference_query_set.json`)¶

This file representing the full input query in a validated internal format defined by this Pydantic schema.

Created automatically from the original query.json.
If --use-msa-server=True, automatically populates:
- main_msa_file_paths: Paths to single-chain .a3m or .npz files
- paired_msa_file_paths: Paths to paired .a3m or .npz files (if heteromer input)
Note: Refer to the Precomputed MSA Documentation for how to specify these fields if you want to use precomputed MSAs instead of MSAs from the Colabfold server.
If --use-templates=True, automatically populates:
- template_alignment_file_path: Path to the preprocessed template cache entry .npz file used for template featurization. By default, template cache entries are automatically created in a short preprocessing step using the raw template alignment files provided under this same field and the template structures identified in the alignment.
- template_entry_chain_ids: List of template chains, identified by their entry (typically PDB) IDs and chain IDs, used for featurization. By default, up to the first 4 of these chains are used.
Note: Refer to the Template How-To Documentation for how to specify these fields if you want to use precomputed template alignments instead of Colabfold alignments for template inputs.

Note: If MSA and template files are persisted between runs, the same inference_query_set.json file can be used to resubmit the query without needing to rerun the template and MSA pipelines. To do so:

Turn off the MSA cleanup option.
pass in the generated inference_query_set.json as the query.json and use --use-msa-server=False and --use-templates=True.

Model seeds should still be set either from the command line or using the seeds field under experiment_settings in the runner.yml.

4.4.2 Model Config (`model_config.json`)¶

This file represents the model settings used to perform inference. The config follows the model configuration file defined here This file represents the model settings used to perform inference. The config follows the model configuration file defined here.

4.4.3 Experiment Config (`experiment_config.json`)¶

This file records the entire state of the experiment, as defined by the InferenceExperimentConfig pydantic model.

🔗 Example:

See the full multimer output for Deoxy human hemoglobin, which were generated with run_multimer.sh. For this example, the colabfold_msas and colabfold_template directories are stored in the same outbut directory.

When processing multimer inputs (e.g., hemoglobin α + β chains), OpenFold3 automatically:

Requests paired MSAs from the ColabFold server
Stores raw alignments in raw/paired/ temporarily
Converts them into per-chain .npz alignments in paired/

4.5 Embeddings¶

At inference you can instruct the model to produce the pair-rep and single-rep embeddings by adjusting the output_writer_settings in your runner.yaml.

This will cause the model to produce a *_latent_output.pt, which can be loaded like so and has the following shape.

output = torch.load("*_latent_output.pt")
print(output.keys())
["si_trunk", "zij_trunk", "atom_positions_predicted"]

If you want to change these outputs, the code is in the model.py

OpenFold3 Inference¶

1. Inference features¶

1.1 Protein¶

1.2 DNA¶

1.3 RNA¶

1.4 Ligand¶

2. Pre-requisites¶

3. Running OpenFold3 Inference¶

3.1 Input Data: Query JSON¶

3.2 Inference Modes by MSA Input¶

3.2.1 🚀 Inference with ColabFold MSA Server (Default)¶

3.2.2 📂 Inference with Precomputed MSAs¶

3.2.3 🚫 Inference Without MSAs¶

3.3 Customized Inference Settings Using runner.yml¶

🖥️ Run on Multiple GPUs or Nodes¶

🌱 Change the random seeds for the model¶

📦 Output in PDB Format¶

📦 Output single and pair model embeddings¶

⏩ Skip full confidence model outputs¶

🧠 Low Memory Mode¶

🔴 AMD ROCm Inference with Triton Kernels¶

3.4 Customized ColabFold MSA Server Settings Using runner.yml¶

Saving MSA outputs¶

Use a Privately Hosted ColabFold MSA Server¶

Save MSAs in A3M Format¶

4. Model Outputs¶

4.1 Prediction Outputs (query/seed/)¶

4.2 Processed MSAs (main/ and paired/)¶

4.3 Mapping outputs (mapping/)¶

4.4 Query Metadata¶

4.4.1 Inference Query Set (inference_query_set.json)¶

4.4.2 Model Config (model_config.json)¶

4.4.3 Experiment Config (experiment_config.json)¶

4.5 Embeddings¶

3.3 Customized Inference Settings Using `runner.yml`¶

3.4 Customized ColabFold MSA Server Settings Using `runner.yml`¶

4.1 Prediction Outputs (`query/seed/`)¶

4.2 Processed MSAs (`main/` and `paired/`)¶

4.3 Mapping outputs (`mapping/`)¶

4.4.1 Inference Query Set (`inference_query_set.json`)¶

4.4.2 Model Config (`model_config.json`)¶

4.4.3 Experiment Config (`experiment_config.json`)¶