--- title: "Run AlphaFold2 on an instance" description: "Install AlphaFold2 in the workspace of a TIR Instance, download its genetic databases, and predict a protein's 3D structure from its sequence." content_type: "how-to" product: "tir-instance" platform: "TIR" url: "/tir/tir-instance/how-to/run-alphafold2-on-an-instance/" topic: ["guides"] --- # Run AlphaFold2 on an instance Install AlphaFold2 and its genetic databases in your instance's workspace, and predict a protein's 3D structure from its amino-acid sequence. AlphaFold2 is DeepMind's open-source model for protein structure prediction. Its own install instructions use Docker. An instance runs without a Docker daemon, so here you install AlphaFold2 and the tools it calls directly, in a conda environment. Keep everything in the workspace at `/home/jovyan`: the AlphaFold2 folder, conda and its environment, the databases, your input, and the predictions. Files there survive restarts and stops. The rest of the container, including `/root` and `/tmp`, is emptied each time the instance restarts. ## Before you begin - An instance in the **Running** state. A GPU instance is recommended, and the GPU commands on this page need a driver for CUDA 12: run `nvidia-smi` on the instance and check that **CUDA Version** shows 12 or later. See [Create an instance](/tir/tir-instance/how-to/create-an-instance/). - A terminal on the instance: a JupyterLab terminal (**File** > **New** > **Terminal**), or an SSH session as `root`. See [Connect to an instance over SSH](/tir/tir-instance/how-to/connect-to-an-instance-over-ssh/). Run these commands in a terminal, where a conda environment you activate stays active from one command to the next; in a notebook, it lasts only for the cell that activated it. - `git` and `wget` on the image. If either is missing, install them as `root` over SSH with `apt-get update && apt-get install -y git wget`. Packages installed with `apt-get` are lost at the next restart, so run that line again after one. - Storage for the databases, chosen as the next section describes. Choose it before you start, because the download takes hours. ## Choose where the databases live AlphaFold2 searches large genetic databases for each prediction. The full set is a 556 GB download and takes 2.62 TB once unpacked. The reduced set takes about 600 GB and is quicker to download and to search. Each set has its own command when you run a prediction. The databases need storage that keeps its data through restarts. These are the places on an instance that do: | Storage | Size | Where it appears | Access | | -------------------------------- | ---------------------- | -------------------------- | -------------------------------------------------- | | Workspace | 30 GB to 15,000 GB | `/home/jovyan` | Read-write, this instance only | | Disk dataset | 10 GB to 15,000 GB | `/datasets/` | Read-write, one instance at a time | | EOS dataset | Set by its bucket | `/datasets/` | Read-only, many instances at once | | Shared File System | 250 GB to 64,000 GB | The mount path you choose | Read-write, many instances at once | | Parallel File System, Delhi only | 1,000 GB to 250,000 GB | The mount path you choose | Read-write, or read-only if you tick **Read Only** | The upper sizes are your account's limits in the region, which E2E can change. An EOS dataset is read-only, so use it only for databases you have already put in the bucket; the download and the predictions need storage you can write to. Data you write anywhere else in the container goes to ephemeral storage, which is emptied on every restart. When ephemeral storage is full, the instance restarts and the data is lost. See [Where your files live on an instance](/tir/tir-instance/concepts/where-your-files-live/). Workspace above 30 GB is billed for as long as the instance exists, even while it is stopped. Datasets and file systems are billed as their own products. See [pricing](https://www.e2enetworks.com/pricing). To grow the workspace, see [Increase the workspace size](/tir/tir-instance/how-to/increase-the-workspace-size/). To mount a dataset or file system, see [Mount datasets and file systems on an instance](/tir/tir-instance/how-to/mount-datasets-and-file-systems/). These commands keep the databases in `/home/jovyan/af-data`. If you keep them on a dataset or file system, use its mount path in place of `/home/jovyan/af-data` in every command. ## Download AlphaFold2 In the terminal, clone the AlphaFold2 repository into the workspace: ```bash cd /home/jovyan git clone https://github.com/google-deepmind/alphafold.git cd alphafold ``` The code is now in `/home/jovyan/alphafold`. ## Install conda in the workspace Install your own conda, Miniforge, in the workspace, so conda and the environment you create with it survive restarts whatever the image includes: ```bash cd /home/jovyan wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh bash Miniforge3-Linux-x86_64.sh -b -p /home/jovyan/miniforge3 ``` The `-b` option runs the install unattended and leaves your shell's startup files unchanged. Then make the `conda` command available in this terminal: ```bash eval "$(/home/jovyan/miniforge3/bin/conda shell.bash hook)" ``` Run this line in every new terminal before you use conda. A line added to `.bashrc`, by you or by `conda init`, is lost at the next start. ## Create the conda environment Create an environment with Python 3.11 in the workspace, activate it, and install the tools AlphaFold2 calls. HMMER, HH-suite, and Kalign run the sequence searches, and `aria2` and `rsync` download the databases. ```bash conda create -y -p /home/jovyan/envs/alphafold -c conda-forge --override-channels python=3.11 conda activate /home/jovyan/envs/alphafold conda install -y -c conda-forge -c bioconda --override-channels hmmer hhsuite=3.3.0 kalign2 aria2 rsync ``` The terminal's prompt starts with the environment's path while it is active. In a new terminal, run the `eval` line from the previous section, then `conda activate /home/jovyan/envs/alphafold`. ## Install the Python packages The PyTorch pre-built image pins every `pip install`, even inside a conda environment, to its own build of PyTorch, so clear that pin before you install anything. With the environment active, install AlphaFold2's packages and the GPU build of JAX: ```bash cd /home/jovyan/alphafold unset PIP_CONSTRAINT pip install -r requirements.txt pip install "jax[cuda12]==0.4.26" ``` `jax[cuda12]` brings the CUDA 12 libraries that let AlphaFold2 use the GPU. The packages go into the environment in `/home/jovyan/envs/alphafold`, so they stay through restarts. AlphaFold2 also needs a file of stereochemical properties in its `common` folder. Download it: ```bash cd /home/jovyan wget -q -P alphafold/alphafold/common/ https://git.scicore.unibas.ch/schwede/openstructure/-/raw/2.2.0/modules/mol/alg/src/stereo_chemical_props.txt ``` ## Download the genetic databases The repository's download script fetches every database and the model parameters into one folder. With the environment active, run one of these two commands, for the reduced or the full set: ```bash cd /home/jovyan/alphafold # reduced databases, about 600 GB of disk: nohup scripts/download_all_data.sh /home/jovyan/af-data reduced_dbs > download.log 2>&1 & # or full databases, 556 GB download and 2.62 TB unpacked: nohup scripts/download_all_data.sh /home/jovyan/af-data > download.log 2>&1 & ``` The download runs in the background for several hours and keeps going if you close the terminal. It writes its progress to `/home/jovyan/alphafold/download.log`. To follow it, run `tail -f download.log`. A restart of the instance ends the download. Until it finishes, avoid restarting or stopping the instance, mounting storage on it, changing its plan, and updating its image, because each of these restarts it. When it is done, `/home/jovyan/af-data` holds one folder per database, named as in the commands below. ## Add your input sequence AlphaFold2 reads the protein's amino-acid sequence from a FASTA file. Create a folder for your input in the workspace: ```bash mkdir -p /home/jovyan/af-input ``` Put your FASTA file in it. The commands below use `T1049.fasta`, a target from the CASP14 structure prediction contest. Use your own file's name in its place. To upload a file from your computer, see [Copy files to and from an instance](/tir/tir-instance/how-to/copy-files-to-and-from-an-instance/). ## Run a prediction Run AlphaFold2 from `/home/jovyan/alphafold`, with the environment active. Use the command that matches the databases you downloaded. Each database path must point at the files the download script made. If you keep them elsewhere, change `/home/jovyan/af-data`. AlphaFold2's own Docker setup lets a long protein use the instance's memory when the GPU's memory is full. Running it directly, you turn that on yourself. Run these two lines in the terminal before the command: ```bash export TF_FORCE_UNIFIED_MEMORY=1 export XLA_PYTHON_CLIENT_MEM_FRACTION=4.0 ``` ### With the full databases ```bash python3 run_alphafold.py --use_gpu_relax=True \ --fasta_paths=/home/jovyan/af-input/T1049.fasta \ --output_dir=/home/jovyan/af-output \ --data_dir=/home/jovyan/af-data \ --pdb70_database_path=/home/jovyan/af-data/pdb70/pdb70 \ --uniref90_database_path=/home/jovyan/af-data/uniref90/uniref90.fasta \ --mgnify_database_path=/home/jovyan/af-data/mgnify/mgy_clusters_2022_05.fa \ --bfd_database_path=/home/jovyan/af-data/bfd/bfd_metaclust_clu_complete_id30_c90_final_seq.sorted_opt \ --uniref30_database_path=/home/jovyan/af-data/uniref30/UniRef30_2021_03 \ --template_mmcif_dir=/home/jovyan/af-data/pdb_mmcif/mmcif_files \ --obsolete_pdbs_path=/home/jovyan/af-data/pdb_mmcif/obsolete.dat \ --max_template_date=2025-03-04 \ --db_preset=full_dbs \ --model_preset=monomer \ --use_precomputed_msas=False ``` ### With the reduced databases The reduced set uses the small BFD database in place of BFD and UniRef30, so the command names the small BFD database and leaves the other two out: ```bash python3 run_alphafold.py --use_gpu_relax=True \ --fasta_paths=/home/jovyan/af-input/T1049.fasta \ --output_dir=/home/jovyan/af-output \ --data_dir=/home/jovyan/af-data \ --pdb70_database_path=/home/jovyan/af-data/pdb70/pdb70 \ --uniref90_database_path=/home/jovyan/af-data/uniref90/uniref90.fasta \ --mgnify_database_path=/home/jovyan/af-data/mgnify/mgy_clusters_2022_05.fa \ --small_bfd_database_path=/home/jovyan/af-data/small_bfd/bfd-first_non_consensus_sequences.fasta \ --template_mmcif_dir=/home/jovyan/af-data/pdb_mmcif/mmcif_files \ --obsolete_pdbs_path=/home/jovyan/af-data/pdb_mmcif/obsolete.dat \ --max_template_date=2025-03-04 \ --db_preset=reduced_dbs \ --model_preset=monomer \ --use_precomputed_msas=False ``` AlphaFold2 searches the databases first, then runs the models and relaxes the structures on the GPU. Like the download, a run ends if the instance restarts. ## Options you can change These are the options you are most likely to change, with what each one does: ```plaintext --fasta_paths the input FASTA file, or several separated by commas --data_dir the folder that holds the databases and model parameters --output_dir where the predictions and their scores are written --max_template_date use only template structures released before this date --db_preset full_dbs or reduced_dbs, matching the databases you downloaded --model_preset monomer, monomer_casp14, monomer_ptm, or multimer --use_precomputed_msas True reuses the sequence searches of an earlier run on the same input --models_to_relax best (the default), all, or none ``` The `multimer` preset predicts a complex of several chains. It also needs the UniProt and PDB seqres database paths, and must leave out the PDB70 database path. Reusing the sequence searches skips the database searches on a repeat run. If relaxation fails, run again with the models to relax set to `none`. ## Read the results AlphaFold2 writes one folder per input to the output folder, named after the FASTA file, such as `/home/jovyan/af-output/T1049`. It holds: ```plaintext ranked_0.pdb ... ranked_4.pdb the five predicted structures, most confident first relaxed_model_1.pdb ... relaxed_model_5.pdb each model's structure after relaxation unrelaxed_model_1.pdb ... unrelaxed_model_5.pdb each model's structure before relaxation ranking_debug.json the confidence scores that set the ranking result_model_1.pkl ... result_model_5.pkl each model's raw output relax_metrics.json figures from the relaxation timings.json the time each stage took features.pkl the model's input msas/ the sequence search results ``` ## View the predicted structure Download the most confident structure, the first ranked file in that list, to your computer. Use the JupyterLab file browser, or copy it as [Copy files to and from an instance](/tir/tir-instance/how-to/copy-files-to-and-from-an-instance/) describes. Open the [NCBI iCn3D viewer](https://www.ncbi.nlm.nih.gov/Structure/icn3d/full.html), select **File** > **Open File**, and select the PDB file. The viewer draws the protein's chain in 3D, and you can rotate and zoom it. ![An AlphaFold2 predicted structure drawn as a magenta backbone trace on a black background, with thin lines for the side chains. The chain folds into two large lobes joined in the middle, with a short tail ending in a helix at the lower left.](/images/tir/tir-instance/alphafold2-predicted-structure.png) A predicted structure looks like this one: the protein's backbone drawn as a continuous trace, here folded into two lobes, with the side chains as thin lines around it. ## Fix common problems ### CUDA out of memory Check that you ran the two `export` lines in [Run a prediction](#run-a-prediction) in this terminal. If the run still stops, use the `monomer` preset rather than `multimer`, or move the instance to a plan with more GPU memory. Memory the run takes from the instance counts against the plan's memory, and a process that goes over it is ended. See [Change the plan of an instance](/tir/tir-instance/how-to/change-the-plan-of-an-instance/). ### Missing files or path errors Check that the FASTA file and every database path in the command exist and match the folders the download script made. ### Permission errors The user that runs AlphaFold2 must be able to read the databases and write to the output folder. Change the owner or the permissions with `chown` and `chmod`. ### Long run times or too little disk Use the reduced databases. When you run the same input again, reuse the earlier sequence searches, as [Options you can change](#options-you-can-change) describes. ### The instance restarted during a download or a run The download or run ended with the restart. Check that everything is in `/home/jovyan` or mounted storage, then start the download or the run again. To find out why the instance restarted, see [The instance restarts on its own](/tir/tir-instance/troubleshooting/tir-instance/#the-instance-restarts-on-its-own). ## Design new sequences next [Run ProteinMPNN on an instance](/tir/tir-instance/how-to/run-proteinmpnn-on-an-instance/) designs new sequences for a structure and checks them with AlphaFold2. For problems with the instance itself, see [Troubleshooting TIR Instances](/tir/tir-instance/troubleshooting/tir-instance/). For more options, see the [AlphaFold repository](https://github.com/google-deepmind/alphafold).