Update fork to AlphaFold 3 v3.0.4

README.md

@@ -2,11 +2,11 @@
 
 # AlphaFold 3
 
-This package provides an implementation of the inference pipeline of AlphaFold
-
-1.  See below for how to access the model parameters. You may only use AlphaFold
-    3 model parameters if received directly from Google. Use is subject to these
-    [terms of use](https://github.com/google-deepmind/alphafold3/blob/main/WEIGHTS_TERMS_OF_USE.md).
+This package provides an implementation of the inference pipeline of
+AlphaFold 3. See below for how to access the model parameters. You may only use
+AlphaFold 3 model parameters if received directly from Google. Use is subject to
+these
+[terms of use](https://github.com/google-deepmind/alphafold3/blob/main/WEIGHTS_TERMS_OF_USE.md).
 
 Any publication that discloses findings arising from using this source code, the
 model parameters or outputs produced by those should [cite](#citing-this-work)
@@ -26,12 +26,9 @@ If you have any questions, please contact the AlphaFold team at
 
 ## Obtaining Model Parameters
 
-This repository contains all necessary code for AlphaFold 3 inference. To
-request access to the AlphaFold 3 model parameters, please complete
-[this form](https://forms.gle/svvpY4u2jsHEwWYS6). Access will be granted at
-Google DeepMind’s sole discretion. We will aim to respond to requests within 2–3
-business days. You may only use AlphaFold 3 model parameters if received
-directly from Google. Use is subject to these
+This repository contains all necessary code for AlphaFold 3 inference. You can
+download the AlphaFold 3 model parameters from
+https://storage.googleapis.com/alphafold3/af3.bin.zst. Use is subject to these
 [terms of use](https://github.com/google-deepmind/alphafold3/blob/main/WEIGHTS_TERMS_OF_USE.md).
 
 ## Installation and Running Your First Prediction

docker/Dockerfile

@@ -77,8 +77,9 @@ WORKDIR /app/alphafold
 # --no-editable: install as a static package.
 # If using this as a recipe for local installation, we recommend removing the
 # --frozen and --no-editable flags.
-RUN --mount=type=cache,target=/root/.cache/uv \ 
-    UV_LINK_MODE=copy uv sync --frozen --all-groups --no-editable
+ARG UV_EXTRAS=""
+RUN --mount=type=cache,target=/root/.cache/uv \
+    UV_LINK_MODE=copy uv sync --frozen --all-groups --no-editable $UV_EXTRAS
 
 # Build chemical components database (this binary was installed by uv sync).
 RUN uv run build_data

docs/input.md

@@ -5,9 +5,20 @@
 You can provide inputs to `run_alphafold.py` in one of two ways:
 
 -   Single input file: Use the `--json_path` flag followed by the path to a
-    single JSON file.
+    single JSON file. This path can be either a local path or a Google Cloud
+    Storage path (starting with `gs://`), if enabled.
 -   Multiple input files: Use the `--input_dir` flag followed by the path to a
-    directory of JSON files.
+    directory of JSON files. This path can be either a local directory path or a
+    GCS path, if enabled.
+-   Within an input file, fields with names ending in `Path` (e.g.
+    `pairedMsaPath`) can be provided as Google Cloud Storage paths, if enabled.
+
+### Note: Google Cloud Storage paths
+
+Google Cloud Storage (`gs://`) paths are supported for certain flags and fields
+if the optional `gcsfs` dependency is installed. See the
+[installation instructions](installation.md#optional-enable-google-cloud-storage-path-support)
+for details and a complete list of supported paths.
 
 ## Input Format
 
@@ -29,6 +40,9 @@ The custom AlphaFold 3 format allows:
 *   Specifying covalent bonds between entities.
 *   Specifying multiple random seeds.
 
+Multiple examples of input JSON files are provided in
+https://github.com/google-deepmind/alphafold3/tree/main/examples.
+
 ## AlphaFold Server JSON Compatibility
 
 The [AlphaFold Server](https://alphafoldserver.com/) uses a separate
@@ -743,6 +757,39 @@ as it could cause issues in the mmCIF format.
 The newly defined ligand can then be used as a standard CCD ligand using its
 custom name, and bonds can be linked to it using its named atom scheme.
 
+### Using user-provided CCD for polymer modifications
+
+The user-provided CCD can also be used for specifying non-canonical amino acids
+or nucleotides in the protein/RNA/DNA chains, not only custom ligands.
+
+In this case, the custom component is referenced from the polymer
+`modifications` field using its CCD component ID:
+
+```json
+{
+  "protein": {
+    "id": "A",
+    "sequence": "MDQHQAFKEATELLEKMKTSSDEERVEYLRKAVRLFNLTSEGQQGELVGKFKEAGVLIRAVDLS",
+    "modifications": [{"ptmType": "MYMOD", "ptmPosition": 30}]
+  }
+}
+```
+
+In the example above, residue 30 is replaced by the custom component `MYMOD`.
+
+*   `ptmType` must match the component ID defined in the user-provided CCD.
+*   The user-provided CCD should describe an appropriate peptide-linking polymer
+    component rather than a free non-polymer ligand.
+*   The user-provided CCD entry should include the expected backbone atoms and
+    bond graph for the residue, adjusted for the residue position in the polymer
+    chain. E.g. atoms and bond graphs for the mid-chain residue and terminal
+    residue may differ.
+
+The same principle applies to RNA and DNA chains. This workflow is useful for
+modeling non-canonical amino acids or nucleotides in the context of polymer
+chains. By contrast, external covalent ligands should generally be modeled as
+ligand entities plus `bondedAtomPairs`.
+
 ### Conformer Generation
 
 The data pipeline attempts to generate a conformer for ligands using RDKit. The

docs/installation.md

@@ -17,8 +17,8 @@ should aid others with different setups. If you are installing locally outside
 of a Docker container, please ensure CUDA, cuDNN, and JAX are correctly
 installed; the
 [JAX installation documentation](https://jax.readthedocs.io/en/latest/installation.html#nvidia-gpu)
-is a useful reference for this case. Please note that the Docker container
-requires that the host machine has CUDA 12.6 installed.
+is a useful reference for this case. Note that the Docker container requires
+that the host machine has CUDA 12.6 installed.
 
 The instructions provided below describe how to:
 
@@ -264,17 +264,13 @@ You can use theses two scripts:
 
 ## Obtaining Model Parameters
 
-To request access to the AlphaFold 3 model parameters, please complete
-[this form](https://forms.gle/svvpY4u2jsHEwWYS6). Access will be granted at
-Google DeepMind’s sole discretion. We will aim to respond to requests within 2–3
-business days. You may only use AlphaFold 3 model parameters if received
-directly from Google. Use is subject to these
+You can download the AlphaFold 3 model parameters from
+https://storage.googleapis.com/alphafold3/af3.bin.zst. Use is subject to these
 [terms of use](https://github.com/google-deepmind/alphafold3/blob/main/WEIGHTS_TERMS_OF_USE.md).
 
-Once access has been granted, download the model parameters to a directory of
-your choosing, referred to as `<MODEL_PARAMETERS_DIR>` in the following
-instructions. As with the databases, this should *not* be a subdirectory in the
-AlphaFold 3 repository directory.
+Download the model parameters to a directory of your choosing, referred to as
+`<MODEL_PARAMETERS_DIR>` in the following instructions. As with the databases,
+this should *not* be a subdirectory in the AlphaFold 3 repository directory.
 
 ## Building the Docker Container That Will Run AlphaFold 3
 
@@ -368,6 +364,33 @@ docker run alphafold3 python run_alphafold.py --help
 
 for more information.
 
+:ledger: **Optional: Enable Google cloud storage path support**
+
+AlphaFold 3 supports reading and writing specific files directly from Google
+Cloud Storage (`gs://` paths). Since GCS is an optional feature, the required
+`gcsfs` dependency is not installed by default. To enable GCS support when
+building the Docker container, pass the `UV_EXTRAS` build argument when running
+`docker build`:
+
+```sh
+docker build --build-arg UV_EXTRAS="--extra gcsfs" -t alphafold3 -f docker/Dockerfile .
+```
+
+The following command-line flags support `gs://` paths:
+
+-   `--input_dir`
+-   `--json_path`
+-   `--output_dir`
+-   `--model_dir`
+-   `--pdb_database_path`
+-   In the JSON input file, fields with names ending in `Path` (e.g.
+    `pairedMsaPath`) can be provided as Google Cloud Storage paths, if enabled.
+
+:warning: All other database paths (e.g., `--db_dir`,
+`--small_bfd_database_path`, etc.) and binary paths (e.g.,
+`--jackhmmer_binary_path`) do **not** support `gs://` paths and must be local
+file paths.
+
 ## Running Using Singularity Instead of Docker
 
 You may prefer to run AlphaFold 3 within Singularity. You'll still need to
@@ -454,3 +477,68 @@ singularity exec \
      --db_dir=/root/public_databases_fallback \
      --output_dir=/root/af_output
 ```
+
+## Running AlphaFold 3 without a GPU (CPU-only)
+
+It is possible to run AlphaFold 3 on a computer without a GPU. Note though that
+this is not an officially supported mode (we don't perform rigorous numerical
+accuracy testing for this mode). This mode can be useful for utilizing machines
+without a GPU if you don't mind the longer folding times (roughly 100x slower
+than on a GPU).
+
+### Direct installation without Docker on Linux or Mac OS
+
+Since JAX doesn't support running natively on Mac GPU as of 2026, you have to
+resort to running AlphaFold 3 in the slow CPU-only mode even though it has a GPU
+(`jax-metal` is unfinished as of July 2026).
+
+1.  Download all required databases and AlphaFold 3 weights (see above).
+2.  Install the [HMMER Suite](http://hmmer.org/). See
+    http://hmmer.org/documentation.html for installation instructions.
+3.  Install [uv](https://docs.astral.sh/uv/). See
+    https://docs.astral.sh/uv/getting-started/installation/ for installation
+    instructions.
+4.  Clone the AlphaFold 3 GitHub repository
+
+    ```sh
+    git clone https://github.com/google-deepmind/alphafold3.git
+    ```
+
+5.  Navigate in the `alphafold3` directory and run the following commands to
+    install AlphaFold 3:
+
+    ```sh
+    cd alphafold3
+    uv venv --python 3.12
+    source .venv/bin/activate
+    uv sync
+    uv run build_data
+    ```
+
+6.  Check the installation by running the AlphaFold 3 data test:
+
+    ```sh
+    uv run python run_alphafold_data_test.py
+    ```
+
+7.  You can now run AlphaFold 3. If you are running on a Linux CPU-only machine,
+    make sure to set flags `--jax_backend="cpu"` and
+    `--flash_attention_implementation="xla"`. If you are running on Mac OS with
+    Apple Silicon, you can set `--jax_backend="mps"` instead and get roughly 3x
+    better inference performance by using the built-in GPU:
+
+    ```sh
+    uv run run_alphafold.py \
+      --json_path="..." \
+      --output_dir="..." \
+      --model_dir="..." \
+      --jax_backend="cpu" \
+      --flash_attention_implementation="xla"
+    ```
+
+#### Running on Mac OS using the Apple Silicon GPU
+
+As an alternative to CPU-only mode, AlphaFold 3 inference can run on the Apple
+Silicon GPU with `--jax_backend="mps"` via the community supported `jax-mps`
+Metal plugin. This is an unofficial and experimental path, but it is roughly 3×
+faster than CPU (possibly more on newer M chips).

docs/known_issues.md

@@ -60,3 +60,23 @@ the genetic search.
 In general, we recommend experimenting with MSA if you are seeing a prediction
 with low predicted confidence. Typically adding more *relevant* sequences in the
 MSA will increase AlphaFold prediction accuracy and model confidence scores.
+
+### Gated Linear Unit Tokamax `NotImplementedError`
+
+When running AlphaFold 3 in certain configurations (e.g. on Mac OS with the MPS
+backend), you might see errors like this:
+
+```
+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.
+```
+
+Tokamax will the chose another implementation and run the prediction
+successfully, so these are safe to ignore.

docs/output.md

@@ -9,6 +9,10 @@ AlphaFold 3 will write its outputs in a directory called `My_first_fold_TEST`
 append a timestamp to the directory name to avoid overwriting existing data
 unless `--force_output_dir` is passed.
 
+The output directory can also be a Google Cloud Storage path (`gs://`) if the
+`gcsfs` dependency is installed (see the
+[installation instructions](installation.md#optional-enable-google-cloud-storage-path-support)).
+
 The following structure is used within the output directory:
 
 *   Sub-directories with results for each sample and seed. There will be
@@ -188,6 +192,8 @@ Summary outputs:
     Can be used for ranking a specific chain, when you care about where the
     chain binds to the rest of the complex and you do not know which other
     chains you expect it to interact with. This is often the case with ligands.
+*   `chain_ids:` A \[num_chains\] array with chain IDs in the same order as all
+    of the other chain-level arrays to make the JSON more self-contained.
 
 Full array outputs:
 

examples/barnase_barstar.json

@@ -0,0 +1,22 @@
+{
+  "name": "barnase_barstar_complex",
+  "sequences": [
+    {
+      "protein": {
+        "id": "A",
+        "sequence": "AQVINTFDGVADYLQTYHKLPDNYITKSEAQALGWVASKGNLADVAPGKSIGGDIFSNREGKLPGKSGRTWREADINYTSGFRNSDRILYSSDWLIYKTTDHYQTFTKIR",
+        "description": "Barnase (ribonuclease), B. amyloliquefaciens (UniProt P00648, mature chain, 110 aa)"
+      }
+    },
+    {
+      "protein": {
+        "id": "B",
+        "sequence": "KKAVINGEQIRSISDLHQTLKKELALPEYYGENLDALWDCLTGWVEYPLVLEWRQFEQSKQLTENGAESVLQVFREAKAEGCDITIILS",
+        "description": "Barstar (barnase inhibitor), B. amyloliquefaciens (UniProt P11540, mature chain, 89 aa)"
+      }
+    }
+  ],
+  "modelSeeds": [42],
+  "dialect": "alphafold3",
+  "version": 4
+}

examples/calmodulin_4calcium.json

@@ -0,0 +1,22 @@
+{
+  "name": "calmodulin_4calcium",
+  "sequences": [
+    {
+      "protein": {
+        "id": "A",
+        "sequence": "MADQLTEEQIAEFKEAFSLFDKDGDGTITTKELGTVMRSLGQNPTEAELQDMINEVDADGNGTIDFPEFLTMMARKMKDTDSEEEIREAFRVFDKDGNGYISAAELRHVMTNLGEKLTDEEVDEMIREADIDGDGQVNYEEFVQMMTAK",
+        "description": "Human calmodulin-1 (UniProt P0DP23, 149 aa)"
+      }
+    },
+    {
+      "ligand": {
+        "id": ["B", "C", "D", "E"],
+        "ccdCodes": ["CA"],
+        "description": "Calcium ions (CCD: CA), 4 copies for 4 EF-hand binding sites"
+      }
+    }
+  ],
+  "modelSeeds": [42],
+  "dialect": "alphafold3",
+  "version": 4
+}

examples/erk2_phosphorylated.json

@@ -0,0 +1,19 @@
+{
+  "name": "ERK2_dual_phosphorylated",
+  "sequences": [
+    {
+      "protein": {
+        "id": "A",
+        "sequence": "MAAAAAAGAGPEMVRGQVFDVGPRYTNLSYIGEGAYGMVCSAYDNVNKVRVAIKKISPFEHQTYCQRTLREIKILLRFRHENIIGINDIIRAPTIEQMKDVYIVQDLMETDLYKLLKTQHLSNDHICYFLYQILRGLKYIHSANVLHRDLKPSNLLLNTTCDLKICDFGLARVADPDHDHTGFLTEYVATRWYRAPEIMLNSKGYTKSIDIWSVGCILAEMLSNRPIFPGKHYLDQLNHILGILGSPSQEDLNCIINLKARNYLLSLPHKNKVPWNRLFPNADSKALDLLDKMLTFNPHKRIEVEQALAHPYLEQYYDPSDEPIAEAPFKFDMELDDLPKEKLKELIFEETARFQPGYRS",
+        "modifications": [
+          {"ptmType": "TPO", "ptmPosition": 185},
+          {"ptmType": "PTR", "ptmPosition": 187}
+        ],
+        "description": "Human ERK2/MAPK1 (UniProt P28482, 360 aa) with activation-loop dual phosphorylation: pThr185 (TPO) + pTyr187 (PTR)"
+      }
+    }
+  ],
+  "modelSeeds": [42],
+  "dialect": "alphafold3",
+  "version": 4
+}

examples/kras_g12c_sotorasib.json

@@ -0,0 +1,25 @@
+{
+  "name": "KRAS_G12C_sotorasib_covalent",
+  "sequences": [
+    {
+      "protein": {
+        "id": "A",
+        "sequence": "MTEYKLVVVGACGVGKSALTIQLIQNHFVDEYDPTIEDSYRKQVVIDGETCLLDILDTAGQEEYSAMRDQYMRTGEGFLCVFAINNTKSFEDIHHYREQIKRVKDSEDVPMVLVGNKCDLPSRTVDTKQAQDLARSYGIPFIETSAKTRQRVEDAFYTLVREIRQYRLKKISKEEKTPGCVKIKKCIIM",
+        "description": "Human KRAS4B G12C mutant (UniProt P01116 with G12C, 189 aa)"
+      }
+    },
+    {
+      "ligand": {
+        "id": "B",
+        "ccdCodes": ["MOV"],
+        "description": "Sotorasib / AMG-510 (CCD: MOV), covalent KRAS G12C inhibitor"
+      }
+    }
+  ],
+  "bondedAtomPairs": [
+    [["A", 12, "SG"], ["B", 1, "C25"]]
+  ],
+  "modelSeeds": [42],
+  "dialect": "alphafold3",
+  "version": 4
+}