AlphaFold 3

https://github.com/google-deepmind/alphafold3
Admin
AlphaFold 3 provides an implementation of the inference pipeline for accurate structure prediction...
Tokens:45,800
Snippets:267
Trust Score:9.4
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Docker Packages and Verify

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Adds the Docker apt repository, installs Docker packages, and verifies the installation with hello-world. Requires the GPG key from the previous step.

```sh
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo docker run hello-world
```

--------------------------------

### Install and configure NVIDIA Container Toolkit for Docker

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Install the NVIDIA Container Toolkit and configure Docker to use it. Sets the Docker runtime and disables cgroups for the container CLI.

```sh
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
nvidia-ctk runtime configure --runtime=docker --config=$HOME/.config/docker/daemon.json
systemctl --user restart docker
sudo nvidia-ctk config --set nvidia-container-cli.no-cgroups --in-place
```

--------------------------------

### Install AlphaFold 3 with uv

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Installs AlphaFold 3 in a virtual environment using uv, then builds the data.

```sh
cd alphafold3
uv venv --python 3.12
source .venv/bin/activate
uv sync
uv run build_data
```

--------------------------------

### Example output of nvidia-smi in Docker

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Example output from the Docker GPU verification command, showing an NVIDIA A100-SXM4-80GB with driver 550.120 and CUDA 12.6.

```text
Mon Nov  11 12:00:00 2024
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 550.120                Driver Version: 550.120        CUDA Version: 12.6     |
|-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA A100-SXM4-80GB          Off |   00000000:00:05.0 Off |                    0 |
| N/A   34C    P0             51W /  400W |       1MiB /  81920MiB |      0%      Default |
|                                         |                        |             Disabled |
+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI        PID   Type   Process name                              GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|  No running processes found                                                             |
+-----------------------------------------------------------------------------------------+
```

--------------------------------

### Enable Rootless Docker on Ubuntu

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Enables rootless Docker on Ubuntu 22.04. Installs required packages and runs the rootless setup script, enabling linger and switching the Docker context to rootless.

```sh
sudo apt-get install -y uidmap systemd-container

sudo machinectl shell $(whoami)@ /bin/bash -c 'dockerd-rootless-setuptool.sh install && sudo loginctl enable-linger $(whoami) && DOCKER_HOST=unix:///run/user/1001/docker.sock docker context use rootless'
```

--------------------------------

### Install Singularity CE 4.2.1

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Install Singularity CE 4.2.1 on Ubuntu (jammy) by downloading the .deb package, installing it with dpkg, and fixing any missing dependencies with apt-get.

```sh
wget https://github.com/sylabs/singularity/releases/download/v4.2.1/singularity-ce_4.2.1-jammy_amd64.deb
sudo dpkg --install singularity-ce_4.2.1-jammy_amd64.deb
sudo apt-get install -f
```

--------------------------------

### Install NVIDIA drivers on Ubuntu

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Install NVIDIA drivers on Ubuntu. Accept the "Pending kernel upgrade" dialog if it appears. Reboot with `sudo reboot now` if the NVIDIA-SMI warning appears. Proceed only if `nvidia-smi` has sensible output.

```sh
sudo apt-get -y install alsa-utils ubuntu-drivers-common
sudo ubuntu-drivers install

sudo nvidia-smi --gpu-reset

nvidia-smi  # Check that the drivers are installed.
```

--------------------------------

### AlphaFold 3 output directory structure example

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/output.md

Example output directory listing for a job named "Hello Fold" run with 1 seed and 5 samples. The distogram and embeddings subdirectories appear only when --save_distogram=true and --save_embeddings=true are passed. The top-ranking prediction files (hello_fold_model.cif, hello_fold_confidences.json, hello_fold_summary_confidences.json) are placed in the root directory.

```txt
hello_fold/
├── seed-1234_distogram                        # Only if --save_distogram=true.
│   └── hello_fold_seed-1234_distogram.npz     # Only if --save_distogram=true.
├── seed-1234_embeddings                       # Only if --save_embeddings=true.
│   └── hello_fold_seed-1234_embeddings.npz    # Only if --save_embeddings=true.
├── seed-1234_sample-0/
│   ├── hello_fold_seed-1234_sample-0_confidences.json
│   ├── hello_fold_seed-1234_sample-0_model.cif
│   └── hello_fold_seed-1234_sample-0_summary_confidences.json
├── seed-1234_sample-1/
│   ├── hello_fold_seed-1234_sample-1_confidences.json
│   ├── hello_fold_seed-1234_sample-1_model.cif
│   └── hello_fold_seed-1234_sample-1_summary_confidences.json
├── seed-1234_sample-2/
│   ├── hello_fold_seed-1234_sample-2_confidences.json
│   ├── hello_fold_seed-1234_sample-2_model.cif
│   └── hello_fold_seed-1234_sample-2_summary_confidences.json
├── seed-1234_sample-3/
│   ├── hello_fold_seed-1234_sample-3_confidences.json
│   ├── hello_fold_seed-1234_sample-3_model.cif
│   └── hello_fold_seed-1234_sample-3_summary_confidences.json
├── seed-1234_sample-4/
│   ├── hello_fold_seed-1234_sample-4_confidences.json
│   ├── hello_fold_seed-1234_sample-4_model.cif
│   └── hello_fold_seed-1234_sample-4_summary_confidences.json
├── TERMS_OF_USE.md
├── hello_fold_confidences.json
├── hello_fold_data.json
├── hello_fold_model.cif
├── hello_fold_ranking_scores.csv
└── hello_fold_summary_confidences.json
```

--------------------------------

### AlphaFold 3 parameters schema example

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/model_parameters.md

Example entries from the AlphaFold 3 parameters schema, showing the format for layer names, dtypes, and shapes. This is used to generate random parameters for performance optimisation on new accelerators.

```text
name=__meta__:__identifier__                                                                                                                                                             dtype=uint8     shape=(64,)
name=diffuser/~/diffusion_head/diffusion_atom_features_layer_norm:scale                                                                                                                  dtype=float32   shape=(128,)
name=diffuser/~/diffusion_head/diffusion_atom_features_to_position_update:weights                                                                                                        dtype=float32   shape=(128, 3)
name=diffuser/~/diffusion_head/diffusion_atom_positions_to_features:weights                                                                                                              dtype=float32   shape=(3, 128)
name=diffuser/~/diffusion_head/diffusion_atom_transformer_decoder/__layer_stack_with_per_layer/diffusion_atom_transformer_decoderadaptive_zero_cond:bias                                 dtype=float32   shape=(3, 128)
name=diffuser/~/diffusion_head/diffusion_atom_transformer_decoder/__layer_stack_with_per_layer/diffusion_atom_transformer_decoderadaptive_zero_cond:weights                              dtype=float32   shape=(3, 128, 128)
name=diffuser/~/diffusion_head/diffusion_atom_transformer_decoder/__layer_stack_with_per_layer/diffusion_atom_transformer_decoderffw_adaptive_zero_cond:bias                             dtype=float32   shape=(3, 128)
name=diffuser/~/diffusion_head/diffusion_atom_transformer_decoder/__layer_stack_with_per_layer/diffusion_atom_transformer_decoderffw_adaptive_zero_cond:weights                          dtype=float32   shape=(3, 128, 128)
name=diffuser/~/diffusion_head/diffusion_atom_transformer_decoder/__layer_stack_with_per_layer/diffusion_atom_transformer_decoderffw_single_cond_bias:weights                            dtype=float32   shape=(3, 128, 128)
name=diffuser/~/diffusion_head/diffusion_atom_transformer_decoder/__layer_stack_with_per_layer/diffusion_atom_transformer_decoderffw_single_cond_layer_norm:scale                        dtype=float32   shape=(3, 128)
name=diffuser/~/diffusion_head/diffusion_atom_transformer_decoder/__layer_stack_with_per_layer/diffusion_atom_transformer_decoderffw_single_cond_scale:bias                              dtype=float32   shape=(3, 128)
name=diffuser/~/diffusion_head/diffusion_atom_transformer_decoder/__layer_stack_with_per_layer/diffusion_atom_transformer_decoderffw_single_cond_scale:weights                           dtype=float32   shape=(3, 128, 128)
name=diffuser/~/diffusion_head/diffusion_atom_transformer_decoder/__layer_stack_with_per_layer/diffusion_atom_transformer_decoderffw_transition1:weights                                 dtype=float32   shape=(3, 128, 512)
name=diffuser/~/diffusion_head/diffusion_atom_transformer_decoder/__layer_stack_with_per_layer/diffusion_atom_transformer_decoderffw_transition2:weights                                 dtype=float32   shape=(3, 256, 128)
name=diffuser/~/diffusion_head/diffusion_atom_transformer_decoder/__layer_stack_with_per_layer/diffusion_atom_transformer_decodergating_query:weights                                    dtype=float32   shape=(3, 128, 128)
name=diffuser/~/diffusion_head/diffusion_atom_transformer_decoder/__layer_stack_with_per_layer/diffusion_atom_transformer_decoderk_projection:weights                                    dtype=float32   shape=(3, 128, 4, 32)
name=diffuser/~/diffusion_head/diffusion_atom_transformer_decoder/__layer_stack_with_per_layer/diffusion_atom_transformer_decoderksingle_cond_bias:weights                               dtype=float32   shape=(3, 128, 128)
```

--------------------------------

### Manual MSA Pairing Example for Two Chains

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md

These three blocks show the manual MSA pairing workflow for two chains DEEP and MIND. The first two blocks are the unpaired MSAs for each chain, with the second including an empty hit to maintain pairing alignment. The third block shows the resulting concatenated MSA after pairing.

```txt
> query
DEEP
> match 1 (organism A)
D--P
> match 2 (organism B)
DD-P
> match 3 (organism C)
DD-P
```

```txt
> query
MIND
> match 1 (organism A)
M--D
> Empty hit to make sure pairing is achieved
----
> match 2 (organism C)
MIN-
```

```txt
> query
DEEPMIND
> match 1 + match 1
D--PM--D
> match 2 + padding
DD-P----
> match 3 + match 2
DD-PMIN-
```

--------------------------------

### Push Docker Image to Local Registry

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Start a local Docker registry on port 5000, tag the built alphafold3 image, and push it to the local registry so Singularity can pull it.

```sh
docker run -d -p 5000:5000 --restart=always --name registry registry:2
docker tag alphafold3 localhost:5000/alphafold3
docker push localhost:5000/alphafold3
```

--------------------------------

### Run AlphaFold 3 data test

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Runs the AlphaFold 3 data test to verify the installation.

```sh
uv run python run_alphafold_data_test.py
```

--------------------------------

### User-provided CCD mmCIF example redefining component X7F

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md

Example user-provided CCD in mmCIF format redefining component X7F. It includes the required _chem_comp, _chem_comp_atom, and _chem_comp_bond sections. The atom section provides ideal coordinates (pdbx_model_Cartn_{x,y,z}_ideal) used as a structural template if RDKit fails to generate conformers. Note that when passing this content in the userCCD field, newlines must be escaped as \n and single quotes used for strings like the chemical formula.

```mmcif
data_MY-X7F
#
_chem_comp.id MY-X7F
_chem_comp.name '5,8-bis(oxidanyl)naphthalene-1,4-dione'
_chem_comp.type non-polymer
_chem_comp.formula 'C10 H6 O4'
_chem_comp.mon_nstd_parent_comp_id ?
_chem_comp.pdbx_synonyms ?
_chem_comp.formula_weight 190.152
#
loop_
_chem_comp_atom.comp_id
_chem_comp_atom.atom_id
_chem_comp_atom.type_symbol
_chem_comp_atom.charge
_chem_comp_atom.pdbx_leaving_atom_flag
_chem_comp_atom.pdbx_model_Cartn_x_ideal
_chem_comp_atom.pdbx_model_Cartn_y_ideal
_chem_comp_atom.pdbx_model_Cartn_z_ideal
MY-X7F C02 C 0 N -1.418 -1.260 0.018
MY-X7F C03 C 0 N -0.665 -2.503 -0.247
MY-X7F C04 C 0 N 0.677 -2.501 -0.235
MY-X7F C05 C 0 N 1.421 -1.257 0.043
MY-X7F C06 C 0 N 0.706 0.032 0.008
MY-X7F C07 C 0 N -0.706 0.030 -0.004
MY-X7F C08 C 0 N -1.397 1.240 -0.037
MY-X7F C10 C 0 N -0.685 2.443 -0.057
MY-X7F C11 C 0 N 0.679 2.445 -0.045
MY-X7F C12 C 0 N 1.394 1.243 -0.013
MY-X7F O01 O 0 N -2.611 -1.301 0.247
MY-X7F O09 O 0 N -2.752 1.249 -0.049
MY-X7F O13 O 0 N 2.750 1.257 -0.001
MY-X7F O14 O 0 N 2.609 -1.294 0.298
MY-X7F H1 H 0 N -1.199 -3.419 -0.452
MY-X7F H2 H 0 N 1.216 -3.416 -0.429
MY-X7F H3 H 0 N -1.221 3.381 -0.082
MY-X7F H4 H 0 N 1.212 3.384 -0.062
MY-X7F H5 H 0 N -3.154 1.271 0.830
MY-X7F H6 H 0 N 3.151 1.241 -0.880
#
loop_
_chem_comp_bond.atom_id_1
_chem_comp_bond.atom_id_2
_chem_comp_bond.value_order
_chem_comp_bond.pdbx_aromatic_flag
O01 C02 DOUB N
O09 C08 SING N
C02 C03 SING N
C02 C07 SING N
C03 C04 DOUB N
C08 C07 DOUB Y
C08 C10 SING Y
C07 C06 SING Y
C10 C11 DOUB Y
C04 C05 SING N
C06 C05 SING N
C06 C12 DOUB Y
C11 C12 SING Y
C05 O14 DOUB N
C12 O13 SING N
C03 H1 SING N
C04 H2 SING N
C10 H3 SING N
C11 H4 SING N
O09 H5 SING N
O13 H6 SING N
#

```

--------------------------------

### Docker mount permission error

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Example error message indicating that the models and data are not in the correct paths (flags named --volume above).

```text
docker: Error response from daemon: error while creating mount source path '/srv/alphafold3_data/models': mkdir /srv/alphafold3_data/models: permission denied.
```

--------------------------------

### Run AlphaFold with sharded databases and Z-values

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/performance.md

Launch AlphaFold with sharded database paths and Z-values. This example uses 16 shards per database and sets Jackhmmer/Nhmmer CPU and parallel shard limits. The run utilizes (2 CPUs) × (16 max parallel shards) × (4 protein dbs) = 128 cores per protein chain and (2 CPUs) × (16 max parallel shards) × (3 RNA dbs) = 96 cores per RNA chain.

```bash
python run_alphafold.py \
    --small_bfd_database_path="bfd-first_non_consensus_sequences.fasta@64" \
    --small_bfd_z_value=65984053 \
    --mgnify_database_path="mgy_clusters_2022_05.fa@512" \
    --mgnify_z_value=623796864 \
    --uniprot_cluster_annot_database_path="uniprot_cluster_annot_2021_04.fasta@256" \
    --uniprot_cluster_annot_z_value=225619586 \
    --uniref90_database_path="uniref90_2022_05.fasta@128" \
    --uniref90_z_value=153742194 \
    --ntrna_database_path="nt_rna_2023_02_23_clust_seq_id_90_cov_80_rep_seq.fasta@256" \
    --ntrna_z_value=76752.808514 \
    --rfam_database_path="rfam_14_9_clust_seq_id_90_cov_80_rep_seq.fasta@16" \
    --rfam_z_value=138.115553 \
    --rna_central_database_path="rnacentral_active_seq_id_90_cov_80_linclust.fasta@64" \
    --rna_central_z_value=13271.415730
    --jackhmmer_n_cpu=2 \
    --jackhmmer_max_parallel_shards=16 \
    --nhmmer_n_cpu=2 \
    --nhmmer_max_parallel_shards=16
```

--------------------------------

### Clone AlphaFold 3 repository

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Clones the AlphaFold 3 repository from GitHub. Requires git to be installed.

```sh
git clone https://github.com/google-deepmind/alphafold3.git
```

--------------------------------

### AlphaFold 3 Full Input JSON Example

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md

Complete AlphaFold 3 input JSON showing all supported sequence types (protein, DNA, RNA, ligand) with modifications, templates, MSA fields, bonded atom pairs, and metadata. Note that this example abbreviates certain fields (e.g., unpairedMsa, mmcif, userCCD) and is not biologically meaningful, so it will not run out of the box.

```json
{
  "name": "Hello fold",
  "modelSeeds": [10, 42],
  "sequences": [
    {
      "protein": {
        "id": "A",
        "sequence": "PVLSCGEWQL",
        "modifications": [
          {"ptmType": "HY3", "ptmPosition": 1},
          {"ptmType": "P1L", "ptmPosition": 5}
        ],
        "description": "10-residue protein with 2 modifications",
        "unpairedMsa": ...,
        "pairedMsa": ""
      }
    },
    {
      "protein": {
        "id": "B",
        "sequence": "RPACQLW",
        "templates": [
          {
            "mmcif": ...,
            "queryIndices": [0, 1, 2, 4, 5, 6],
            "templateIndices": [0, 1, 2, 3, 4, 8]
          }
        ]
      }
    },
    {
      "dna": {
        "id": "C",
        "sequence": "GACCTCT",
        "modifications": [
          {"modificationType": "6OG", "basePosition": 1},
          {"modificationType": "6MA", "basePosition": 2}
        ]
      }
    },
    {
      "rna": {
        "id": "E",
        "sequence": "AGCU",
        "modifications": [
          {"modificationType": "2MG", "basePosition": 1},
          {"modificationType": "5MC", "basePosition": 4}
        ],
        "unpairedMsa": ...
      }
    },
    {
      "ligand": {
        "id": ["F", "G", "H"],
        "ccdCodes": ["ATP"]
      }
    },
    {
      "ligand": {
        "id": "I",
        "ccdCodes": ["NAG", "FUC"]
      }
    },
    {
      "ligand": {
        "id": "Z",
        "smiles": "CC(=O)OC1C[NH+]2CCC1CC2"
      }
    }
  ],
  "bondedAtomPairs": [
    [["A", 1, "CA"], ["G", 1, "CHA"]],
    [["I", 1, "O6"], ["I", 2, "C1"]]
  ],
  "userCCD": ...,
  "dialect": "alphafold3",
  "version": 4
}
```

--------------------------------

### Build AlphaFold 3 Docker image with GCS support

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Builds the AlphaFold 3 Docker image with Google Cloud Storage (gs://) path support by passing the UV_EXTRAS build argument to install the gcsfs dependency.

```sh
docker build --build-arg UV_EXTRAS="--extra gcsfs" -t alphafold3 -f docker/Dockerfile .
```

--------------------------------

### Map query residues to template residues

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md

Example of specifying the mapping {0: 0, 1: 2, 2: 5, 3: 6} using two lists of the same length. Note that unresolved mmCIF residues must be accounted for when specifying template indices.

```json
"queryIndices":    [0, 1, 2, 3],
"templateIndices": [0, 2, 5, 6]
```

--------------------------------

### AlphaFold 3 CMake build configuration

Source: https://github.com/google-deepmind/alphafold3/blob/main/CMakeLists.txt

CMake configuration for building the AlphaFold 3 C++ extension. It sets up FetchContent dependencies (abseil-cpp, pybind11, pybind11_abseil, cifpp, dssp), requires Python3 with NumPy, compiles all .cc files under src/alphafold3 (excluding tests, mains, and benchmarks), and installs the resulting module and license files into the alphafold3 package.

```cmake
cmake_minimum_required(VERSION 3.28)

# This forces Git to use the 'files' backend for all FetchContent operations.
# This fixes libcifpp and dssp incompatibility with newer git versions.
set(ENV{GIT_CONFIG_PARAMETERS} "'init.defaultRefFormat=files'")

project(
  "${SKBUILD_PROJECT_NAME}"
  LANGUAGES CXX
  VERSION "${SKBUILD_PROJECT_VERSION}")

include(FetchContent)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_POSITION_INDEPENDENT_CODE TRUE)
set(ABSL_PROPAGATE_CXX_STD ON)

# Remove support for scan deps, which is only useful when using C++ modules.
unset(CMAKE_CXX_SCANDEP_SOURCE)

FetchContent_Declare(
  abseil-cpp
  GIT_REPOSITORY https://github.com/abseil/abseil-cpp
  GIT_TAG d7aaad83b488fd62bd51c81ecf16cd938532cc0a # 20240116.2
  EXCLUDE_FROM_ALL)

FetchContent_Declare(
  pybind11
  GIT_REPOSITORY https://github.com/pybind/pybind11
  GIT_TAG 2e0815278cb899b20870a67ca8205996ef47e70f # v2.12.0
  EXCLUDE_FROM_ALL)

FetchContent_Declare(
  pybind11_abseil
  GIT_REPOSITORY https://github.com/pybind/pybind11_abseil
  GIT_TAG bddf30141f9fec8e577f515313caec45f559d319 # HEAD @ 2024-08-07
  EXCLUDE_FROM_ALL)

FetchContent_Declare(
  cifpp
  GIT_REPOSITORY https://github.com/pdb-redo/libcifpp
  GIT_TAG ac98531a2fc8daf21131faa0c3d73766efa46180 # v7.0.3
  # Don't `EXCLUDE_FROM_ALL` as necessary for build_data.
)

FetchContent_Declare(
  dssp
  GIT_REPOSITORY https://github.com/PDB-REDO/dssp
  GIT_TAG 57560472b4260dc41f457706bc45fc6ef0bc0f10 # v4.4.7
  EXCLUDE_FROM_ALL)

FetchContent_MakeAvailable(pybind11 abseil-cpp pybind11_abseil cifpp dssp)

find_package(
  Python3
  COMPONENTS Interpreter Development NumPy
  REQUIRED)

include_directories(${PYTHON_INCLUDE_DIRS})
include_directories(src/)

file(GLOB_RECURSE cpp_srcs src/alphafold3/*.cc)
list(FILTER cpp_srcs EXCLUDE REGEX ".*\(_test\|_main\|_benchmark\).cc$")

add_compile_definitions(NPY_NO_DEPRECATED_API=NPY_1_7_API_VERSION)

pybind11_add_module(cpp ${cpp_srcs})

target_link_libraries(
  cpp
  PRIVATE absl::check
          absl::flat_hash_map
          absl::node_hash_map
          absl::strings
          absl::status
          absl::statusor
          absl::log
          pybind11_abseil::absl_casters
          Python3::NumPy
          dssp::dssp
          cifpp::cifpp)

target_compile_definitions(cpp PRIVATE VERSION_INFO=${PROJECT_VERSION})
install(TARGETS cpp LIBRARY DESTINATION alphafold3)
install(
  FILES LICENSE
        OUTPUT_TERMS_OF_USE.md
        WEIGHTS_PROHIBITED_USE_POLICY.md
        WEIGHTS_TERMS_OF_USE.md
  DESTINATION alphafold3)
```

--------------------------------

### Adjust pair_transition_shard_spec for A100 40 GB

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/performance.md

Configuration change for running AlphaFold 3 on a single NVIDIA A100 (40 GB) with inputs up to 4,352 tokens. The format is (num_tokens_upper_bound, shard_size); shard_size=None means no upper bound. This configuration has lower throughput than the 80 GB setup.

```python
  pair_transition_shard_spec: Sequence[_Shape2DType] = (
      (2048, None),
      (3072, 1024),
      (None, 512),
  )
```

--------------------------------

### Set compilation buckets with --buckets flag

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/performance.md

Pass this flag to run_alphafold.py to define custom compilation bucket sizes. With input token sizes 5132, 5280, and 5342, this configuration compiles the model only once for bucket size 5376 instead of three separate compilations. For this specific example, --buckets 5376 alone is sufficient; the full list is a more general solution for diverse input sizes.

```bash
--buckets 256,512,768,1024,1280,1536,2048,2560,3072,3584,4096,4608,5120,5376
```

--------------------------------

### Tokamax Gated Linear Unit NotImplementedError traceback

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/known_issues.md

Example error output when running AlphaFold 3 on certain configurations (e.g., Mac OS with MPS backend). The error is safe to ignore as Tokamax will choose another implementation and run successfully.

```plaintext
NotImplementedError: Not supported on gpu.
Failed to run implementation
Traceback (most recent call last):
File "tokamax/_src/ops/gated_linear_unit/api.py", line 114, in gated_linear_unit
  return fn(x, weights, activation=activation, precision=precision)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "tokamax/_src/ops/op.py", line 197, in __call__
  raise NotImplementedError(f"Not supported on {device.device_kind}.")
NotImplementedError: Not supported on gpu.
```

--------------------------------

### Show run_alphafold.py help

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Displays help for run_alphafold.py, which supports many flags for controlling performance, running on multiple input files, and specifying external binary paths.

```sh
docker run alphafold3 python run_alphafold.py --help
```

--------------------------------

### Run AlphaFold 3 in Singularity (Placeholder)

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Placeholder command showing how to run AlphaFold 3 inside the Singularity container; replace <<args>> with the actual arguments.

```sh
singularity exec --nv alphafold3.sif <<args>>
```

--------------------------------

### Download genetic databases with fetch_databases.sh

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Downloads and sets up all required genetic databases. The script downloads from a GCS mirror with versions matching the AlphaFold 3 paper. Default <DB_DIR> is $HOME/public_databases. The download directory should not be a subdirectory of the repository. Total download size is about 252 GB, unzipped 630 GB. Running in a screen or tmux session is recommended.

```sh
cd alphafold3  # Navigate to the directory with cloned AlphaFold 3 repository.
./fetch_databases.sh [<DB_DIR>]
```

--------------------------------

### Expected database directory structure

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Expected directory structure after fetch_databases.sh completes. Lists the database files and the mmcif_files directory.

```sh
mmcif_files/  # Directory containing ~200k PDB mmCIF files.
bfd-first_non_consensus_sequences.fasta
mgy_clusters_2022_05.fa
nt_rna_2023_02_23_clust_seq_id_90_cov_80_rep_seq.fasta
pdb_seqres_2022_09_28.fasta
rfam_14_9_clust_seq_id_90_cov_80_rep_seq.fasta
rnacentral_active_seq_id_90_cov_80_linclust.fasta
uniprot_all_2021_04.fa
uniref90_2022_05.fa
```

--------------------------------

### Escape SMILES string with jq

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md

Uses the `jq` command-line tool to JSON-escape a SMILES string. Replace the example SMILES with your own.

```bash
jq -R . <<< 'CCC[C@@H](O)CC\C=C\C=C\C#CC#C\C=C\CO'  # Replace with your SMILES.
```

--------------------------------

### Create Google Cloud VM for AlphaFold3

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Creates a Google Cloud VM for running AlphaFold3. Use --machine-type a2-ultragpu-1g for full performance or a2-highgpu-1g for smaller predictions; replace --zone us-central1-a if needed for quota. Provisions Ubuntu 22.04 LTS with 12 CPUs, 170 GB RAM, 1 TB disk, and an NVIDIA A100 80 GB GPU.

```sh
gcloud compute instances create alphafold3 \
    --machine-type a2-ultragpu-1g \
    --zone us-central1-a \
    --image-family ubuntu-2204-lts \
    --image-project ubuntu-os-cloud \
    --maintenance-policy TERMINATE \
    --boot-disk-size 1000 \
    --boot-disk-type pd-balanced
```

--------------------------------

### Run AlphaFold 3 with SSD and fallback database directories

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Runs AlphaFold 3 with databases split between an SSD and a slower disk, mounting both and specifying db_dir multiple times for fast access with fallback.

```sh
docker run -it \
    --volume $HOME/af_input:/root/af_input \
    --volume $HOME/af_output:/root/af_output \
    --volume <MODEL_PARAMETERS_DIR>:/root/models \
    --volume <SSD_DB_DIR>:/root/public_databases \
    --volume <DB_DIR>:/root/public_databases_fallback \
    --gpus all \
    alphafold3 \
    python run_alphafold.py \
    --json_path=/root/af_input/fold_input.json \
    --model_dir=/root/models \
    --db_dir=/root/public_databases \
    --db_dir=/root/public_databases_fallback \
    --output_dir=/root/af_output
```

--------------------------------

### Shuffle and split fasta with seqkit

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/performance.md

Shuffle the sequences in the fasta file and then split the shuffled fasta into s shards. Use these commands to prepare genetic databases for sharding.

```bash
seqkit shuffle --two-pass <db.fasta>
```

```bash
seqkit split2 --by-part <s> <db.fasta>
```

--------------------------------

### Escape SMILES string with Python json.dumps

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md

Python alternative to JSON-escape a SMILES string using `json.dumps`. The raw string `r'...'` preserves backslashes; replace the example SMILES with your own.

```python
import json

smiles = r'CCC[C@@H](O)CC\C=C\C=C\C#CC#C\C=C\CO'  # Replace with your SMILES.
print(json.dumps(smiles))
```

--------------------------------

### Set custom unpairedMsa for protein chain

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md

Example of setting a custom unpaired MSA for a protein chain while disabling paired MSA and templates. The sequence field is left as an ellipsis placeholder in the source.

```json
{
  "protein": {
    "id": "A",
    "sequence": ...,
    "unpairedMsa": "The A3M you want to run with",
    "pairedMsa": "",
    "templates": []
  }
}
```

--------------------------------

### Add Docker GPG Key on Ubuntu

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Adds Docker's official GPG key on Ubuntu 22.04 LTS. Run these commands before adding the Docker repository.

```sh
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
```

--------------------------------

### Run AlphaFold 3 with Singularity (Standard)

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Run AlphaFold 3 with Singularity, binding input, output, model parameters, and database directories, and passing the required run_alphafold.py arguments.

```sh
singularity exec \
     --nv \
     --bind $HOME/af_input:/root/af_input \
     --bind $HOME/af_output:/root/af_output \
     --bind <MODEL_PARAMETERS_DIR>:/root/models \
     --bind <DB_DIR>:/root/public_databases \
     alphafold3.sif \
     python run_alphafold.py \
     --json_path=/root/af_input/fold_input.json \
     --model_dir=/root/models \
     --db_dir=/root/public_databases \
     --output_dir=/root/af_output
```

--------------------------------

### Run template-free by omitting MSA fields

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md

Alternative way to run template-free by fully omitting the MSA fields and setting templates to an empty list.

```json
"protein": {
  "id": "A",
  "sequence": ...,
  "templates": []
}
```

--------------------------------

### Run AlphaFold 3 with SSD Databases

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Run AlphaFold 3 with databases on SSD, binding the SSD directory as the primary database and the regular directory as a fallback, and passing both --db_dir flags.

```sh
singularity exec \
     --nv \
     --bind $HOME/af_input:/root/af_input \
     --bind $HOME/af_output:/root/af_output \
     --bind <MODEL_PARAMETERS_DIR>:/root/models \
     --bind <SSD_DB_DIR>:/root/public_databases \
     --bind <DB_DIR>:/root/public_databases_fallback \
     alphafold3.sif \
     python run_alphafold.py \
     --json_path=/root/af_input/fold_input.json \
     --model_dir=/root/models \
     --db_dir=/root/public_databases \
     --db_dir=/root/public_databases_fallback \
     --output_dir=/root/af_output
```

--------------------------------

### Build AlphaFold 3 Docker image with expanded file descriptor limits

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Builds the AlphaFold 3 Docker image while expanding file descriptor limits to avoid the 'No file descriptors available (os error 24)' error on systems like AlmaLinux/Rocky/RHEL.

```sh
docker build --ulimit nofile=65535:65535 -t alphafold3 -f docker/Dockerfile .
```

--------------------------------

### Build Singularity Container from Docker Image

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Build the Singularity container (alphafold3.sif) from the Docker image in the local registry, using SINGULARITY_NOHTTPS=1 to allow HTTP.

```sh
SINGULARITY_NOHTTPS=1 singularity build alphafold3.sif docker://localhost:5000/alphafold3:latest
```

--------------------------------

### Verify GPU Access in Singularity Container

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Verify the Singularity image can access the GPU by running nvidia-smi inside the container with --nv.

```sh
singularity exec --nv alphafold3.sif sh -c 'nvidia-smi'
```

--------------------------------

### Set GPU memory environment variables for up to 5,120 tokens

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/performance.md

These environment variables, set by default in the Dockerfile, enable folding a single input of up to 5,120 tokens on a single A100 (80 GB) or H100 (80 GB) GPU.

```sh
ENV XLA_PYTHON_CLIENT_PREALLOCATE=true
ENV XLA_CLIENT_MEM_FRACTION=0.95
```

--------------------------------

### Run AlphaFold 3 on CPU-only Linux

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Runs AlphaFold 3 inference on a CPU-only Linux machine, setting the JAX backend to CPU and the flash attention implementation to XLA.

```sh
uv run run_alphafold.py \
  --json_path="..." \
  --output_dir="..." \
  --model_dir="..." \
  --jax_backend="cpu" \
  --flash_attention_implementation="xla"
```

--------------------------------

### Build AlphaFold 3 Docker image

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Builds the AlphaFold 3 Docker container with all required Python dependencies.

```sh
docker build -t alphafold3 -f docker/Dockerfile .
```

--------------------------------

### Run template-free with explicit null MSAs

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md

Runs template-free prediction while still performing genetic search and building MSA. Requires setting both unpairedMsa and pairedMsa to null and templates to an empty list.

```json
"protein": {
  "id": "A",
  "sequence": ...,
  "pairedMsa": null,
  "unpairedMsa": null,
  "templates": []
}
```

--------------------------------

### Run AlphaFold 3 with Docker

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Runs AlphaFold 3 in the Docker container, mounting the input, output, model parameters, and database directories. The mounted directories must match those used when downloading databases and model weights. You may need to create and make writable the output directory before running.

```sh
docker run -it \
    --volume $HOME/af_input:/root/af_input \
    --volume $HOME/af_output:/root/af_output \
    --volume <MODEL_PARAMETERS_DIR>:/root/models \
    --volume <DB_DIR>:/root/public_databases \
    --gpus all \
    alphafold3 \
    python run_alphafold.py \
    --json_path=/root/af_input/fold_input.json \
    --model_dir=/root/models \
    --output_dir=/root/af_output
```

--------------------------------

### Generate random AlphaFold 3 parameters

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/model_parameters.md

Generates random AlphaFold 3 parameters and writes them to a zstandard-compressed file. The identifier parameter is set to zeros, while all other parameters are sampled uniformly between -1 and 1 to avoid zero-only shortcuts in accelerators.

```python
from alphafold3.model import params
import numpy as np
import zstandard

parameters = ...  # Data from the parameters schema.

with zstandard.open('random_weights.bin.zst', 'wb') as compressed:
  for scope_name, shape, dtype in parameters:
    if scope_name == '__meta__:__identifier__':
      # The identifier can be all zeros.
      arr = np.zeros(shape=shape, dtype=dtype)
    else:
      # Do not use all-zero params, instead sample uniformly between -1 and 1.
      arr = np.random.uniform(low=-1, high=1, size=shape).astype(dtype)
    scope_name = scope_name.split(':')
    compressed.write(params.encode_record(*scope_name, arr))
```

--------------------------------

### Verify GPU access in Docker container

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Verify that Docker containers can access the GPU by running `nvidia-smi` inside a CUDA 12.6 container.

```sh
docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu22.04 nvidia-smi
```

--------------------------------

### Enable unified memory environment variables

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/performance.md

Enable unified memory to run AlphaFold 3 on inputs larger than 5,120 tokens or on GPUs with less memory (e.g., A100 40 GB). This spills GPU memory to host memory to prevent OOM, at the cost of slower performance.

```sh
ENV XLA_PYTHON_CLIENT_PREALLOCATE=false
ENV TF_FORCE_UNIFIED_MEMORY=true
ENV XLA_CLIENT_MEM_FRACTION=3.2
```

--------------------------------

### Use pre-computed MSA with template search

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md

Runs with pre-computed MSA while letting AlphaFold 3 search for templates. The profile for Hmmsearch is built from the provided unpairedMsa.

```json
"protein": {
  "id": "A",
  "sequence": ...,
  "unpairedMsa": ...,
  "pairedMsa": ...,
  "templates": null
}
```

--------------------------------

### NVIDIA-SMI driver communication warning

Source: https://github.com/google-deepmind/alphafold3/blob/main/docs/installation.md

Warning shown by `nvidia-smi` when the driver is not communicating. Reboot the instance with `sudo reboot now` to reset the GPU if this appears.

```text
NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver.
Make sure that the latest NVIDIA driver is installed and running.
```
Tokens:
Raw