Skip to content

AlphaFold♯

AlphaFold requires some databases to run. These databases may be different depending on the version of AlphaFold being used. These have been downloaded to Picotte in:

  • /beegfs/AlphaFoldDatabases (for AlphaFold 2.2.4)
  • /beegfs/AlphaFoldDatabases-2-3-1 (for AlphaFold 2.3.1)
  • /beegfs/AlphaFoldDatabases-2-3-2 (for AlphaFold 2.3.1)

Rather than using the actual path, the AlphaFold modulefile defines the environment variable ALPHAFOLD_DATADIR correctly for the version of AlphaFold being used.

UniProt♯

The Universal Protein Resource (UniProt) is a comprehensive resource for protein sequence and annotation data. The UniProt database is very extensive, and cannot be fit onto either of Picotte's storage systems. Instead, the UniProt API should be used for programmatic access to only the data needed.

For info on accessing UniProt data, refer to the following:

* UniProt Video * UniProt Knowledgebase * UniProt API Documentation

title: AlphaFold2 permalink: /AlphaFold2/

AlphaFold2[1][2][3] predicts protein structures using machine learning.

In the rest of this document, AlphaFold2 will be referred to as just "AlphaFold".

Installed Versions♯

AlphaFold 2.2.4 and 2.3.1 are installed on Picotte as a Singularity container. Use the appropriate modulefile:

alphafold/2.2.4 alphafold/2.3.1

The Singularity versions match the released AlphaFold versions:

AlphaFold Databases♯

AlphaFold requires 2.3 TB of data to run. That data has been downloaded to Picotte and is available to all. The data is stored on the Scratch filesystem. The database directory is given by the environment variable ALPHAFOLD_DATADIR once the modulefile is loaded. The run_singularity.py script is aware of the existing database paths.

Please DO NOT re-download the AlphaFold databases. If updates are needed, please contact urcf-support@drexel.edu

Running AlphaFold♯

The Singularity container which holds AlphaFold is run by a wrapper Python script, run_singularity.py. Output from AlphaFold will go to the job's local scratch directory, which must then be copied to a permanent location (group or home directory).

Note:

  1. AlphaFold can run only on a single node.
  2. AlphaFold should be able to use multiple GPU devices. BUT please confirm for yourself that your specific workload will use multiple GPUs.
  3. AlphaFold is actually a workflow which runs separate programs. Some of those programs are CPU-only.
  4. The AlphaFold modulefile loads the specific version of Python that it requires. This may or may not conflict with the version of Python you may have set up by default.

To run either of the examples below, first download a FASTA file:

[juser@picotte001 ~]$ wget "https://predictioncenter.org/casp14/target.cgi?target=T1050&view=sequence" -O T1050.fasta

Running AlphaFold 2.x.x♯

Create a job script named "alphafoldtest.sh":

#!/bin/bash
#SBATCH -p gpu
#SBATCH --time=18:00:00
#SBATCH --gpus=4
#SBATCH --cpus-per-gpu=12
#SBATCH --mem-per-gpu=45G

### FIXME change to appropriate version string
module load alphafold/2.3.1

### Check values of some environment variables
echo ALPHAFOLD_DIR=$ALPHAFOLD_DIR
echo ALPHAFOLD_DATADIR=$ALPHAFOLD_DATADIR

###
### README This runs AlphaFold 2.3.1 on the T1050.fasta file
###

# AlphaFold should use all GPU devices available to the job by default.
#
# To run the CASP14 evaluation, use:
#   --model_preset=monomer_casp14
#
# To benchmark, running multiple JAX model evaluations (NB this
# significantly increases run time):
#   --benchmark

# Run AlphaFold; default is to use GPUs, i.e. "--use_gpu" can be omitted.
python3 ${ALPHAFOLD_DIR}/singularity/run_singularity.py \
    --use_gpu \
    --data_dir=${ALPHAFOLD_DATADIR} \
    --fasta_paths=T1050.fasta \
    --max_template_date=2020-05-14 \
    --db_preset=reduced_dbs \
    --model_preset=monomer

echo INFO: AlphaFold returned $?

### Copy Alphafold output back to directory where "sbatch" command was issued.
mkdir $SLURM_SUBMIT_DIR/Output-$SLURM_JOB_ID
cp -R $TMPDIR $SLURM_SUBMIT_DIR/Output-$SLURM_JOB_ID

Submit the job script with: sbatch alphafoldtest.sh. N.B. This may take several hours to complete.

Documentation♯

Consult the official documentation for details.[4]

Citing AlphaFold♯

If you use AlphaFold in your work, please cite:

Jumper, J., Evans, R., Pritzel, A. et al. Highly accurate protein structure prediction with AlphaFold. Nature 596, 583–589 (2021). https://doi.org/10.1038/s41586-021-03819-2

@Article{AlphaFold2021,
  author  = {Jumper, John and Evans, Richard and Pritzel, Alexander and Green, Tim and Figurnov, Michael and Ronneberger, Olaf and Tunyasuvunakool, Kathryn and Bates, Russ and {\v{Z}}{\'\i}dek, Augustin and Potapenko, Anna and Bridgland, Alex and Meyer, Clemens and Kohl, Simon A A and Ballard, Andrew J and Cowie, Andrew and Romera-Paredes, Bernardino and Nikolov, Stanislav and Jain, Rishub and Adler, Jonas and Back, Trevor and Petersen, Stig and Reiman, David and Clancy, Ellen and Zielinski, Michal and Steinegger, Martin and Pacholska, Michalina and Berghammer, Tamas and Bodenstein, Sebastian and Silver, David and Vinyals, Oriol and Senior, Andrew W and Kavukcuoglu, Koray and Kohli, Pushmeet and Hassabis, Demis},
  journal = {Nature},
  title   = {Highly accurate protein structure prediction with {AlphaFold}},
  year    = {2021},
  doi     = {10.1038/s41586-021-03819-2},
  note    = {(Accelerated article preview)},
}

Source Code♯

run_singularity.py
#!/usr/bin/env python3
# Copyright 2023 David Chin
#
# This file is part of alphafold_singularity.
#
# alphafold_singularity is free software: you can redistribute it and/or
# modify it under the terms of the GNU General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# alphafold_singularity is distributed in the hope that it will be
# useful, but WITHOUT ANY WARRANTY; without even the implied warranty
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with alphafold_singularity. If not, see <https://www.gnu.org/licenses/>.

"""Singularity launch script for Alphafold Singularity image."""

import os
import sys
import pathlib
import signal
from typing import Tuple

from absl import app
from absl import flags
from absl import logging
from spython.main import Client

import tempfile
import subprocess


#### USER CONFIGURATION ####

# Path to AlphaFold Singularity image. This relies on
# the environment variable ALPHAFOLD_DIR which is the
# directory where AlphaFold is installed.
singularity_image = Client.load(os.path.join(os.environ['ALPHAFOLD_DIR'], 'alphafold.sif'))

# tmp directory
if 'TMP' in os.environ:
    tmp_dir = os.environ['TMP']
elif 'TMPDIR' in os.environ:
    tmp_dir = os.environ['TMPDIR']
else:
    tmp_dir = '/tmp'

# Default path to a directory that will store the results.
output_dir_default = tempfile.mkdtemp(dir=tmp_dir, prefix='alphafold')

logging.info(f'INFO: tmp_dir = {tmp_dir}')
logging.info(f'INFO: output_dir_default = {output_dir_default}')

#### END USER CONFIGURATION ####

### These flags correspond to the flags defined in ../run_alphafold.py
flags.DEFINE_bool(
    'use_gpu', True, 'Enable NVIDIA runtime to run with GPUs.')
flags.DEFINE_enum(
    'models_to_relax', 'best', ['best', 'all', 'none'],
    'The models to run the final relaxation step on. '
    'If `all`, all models are relaxed, which may be time '
    'consuming. If `best`, only the most confident model is '
    'relaxed. If `none`, relaxation is not run. Turning off '
    'relaxation might result in predictions with '
    'distracting stereochemical violations but might help '
    'in case you are having issues with the relaxation '
    'stage.')
flags.DEFINE_bool(
    'enable_gpu_relax', True, 'Run relax on GPU if GPU is enabled.')
flags.DEFINE_string(
    'gpu_devices', 'all',
    'Comma separated list of devices to pass to NVIDIA_VISIBLE_DEVICES.')
flags.DEFINE_list(
    'fasta_paths', None, 'Paths to FASTA files, each containing a prediction '
    'target that will be folded one after another. If a FASTA file contains '
    'multiple sequences, then it will be folded as a multimer. Paths should be '
    'separated by commas. All FASTA paths must have a unique basename as the '
    'basename is used to name the output directories for each prediction.')
flags.DEFINE_string(
    'output_dir', output_dir_default,
    'Path to a directory that will store the results.')
flags.DEFINE_string(
    'data_dir', None,
    'Path to directory with supporting data: AlphaFold parameters and genetic '
    'and template databases. Set to the target of download_all_databases.sh.')
flags.DEFINE_string(
    'docker_image_name', 'alphafold', 'Name of the AlphaFold Docker image.')
flags.DEFINE_string(
    'max_template_date', None,
    'Maximum template release date to consider (ISO-8601 format: YYYY-MM-DD). '
    'Important if folding historical test sets.')
flags.DEFINE_enum(
    'db_preset', 'full_dbs', ['full_dbs', 'reduced_dbs'],
    'Choose preset MSA database configuration - smaller genetic database '
    'config (reduced_dbs) or full genetic database config (full_dbs)')
flags.DEFINE_enum(
    'model_preset', 'monomer',
    ['monomer', 'monomer_casp14', 'monomer_ptm', 'multimer'],
    'Choose preset model configuration - the monomer model, the monomer model '
    'with extra ensembling, monomer model with pTM head, or multimer model')
flags.DEFINE_integer('num_multimer_predictions_per_model', 5, 'How many '
                     'predictions (each with a different random seed) will be '
                     'generated per model. E.g. if this is 2 and there are 5 '
                     'models then there will be 10 predictions per input. '
                     'Note: this FLAG only applies if model_preset=multimer')
flags.DEFINE_boolean(
    'benchmark', False,
    'Run multiple JAX model evaluations to obtain a timing that excludes the '
    'compilation time, which should be more indicative of the time required '
    'for inferencing many proteins.')
flags.DEFINE_boolean(
    'use_precomputed_msas', False,
    'Whether to read MSAs that have been written to disk instead of running '
    'the MSA tools. The MSA files are looked up in the output directory, so it '
    'must stay the same between multiple runs that are to reuse the MSAs. '
    'WARNING: This will not check if the sequence, database or configuration '
    'have changed.')
flags.DEFINE_string(
    'docker_user', f'{os.geteuid()}:{os.getegid()}',
    'UID:GID with which to run the Docker container. The output directories '
    'will be owned by this user:group. By default, this is the current user. '
    'Valid options are: uid or uid:gid, non-numeric values are not recognised '
    'by Docker unless that user has been created within the container.')

FLAGS = flags.FLAGS

_ROOT_MOUNT_DIRECTORY = '/mnt/'


def _create_bind(bind_name: str, path: str) -> Tuple[str, str]:
  """Create a bind point for each file and directory used by the model."""
  path = os.path.abspath(path)
  source_path = os.path.dirname(path) if bind_name != 'data_dir' else path
  target_path = os.path.join(_ROOT_MOUNT_DIRECTORY, bind_name)

  logging.info('Binding %s -> %s', source_path, target_path)

  # NOTE singularity binds are read-only by default
  if bind_name == 'data_dir':
    data_path = target_path
  else:
    data_path = f'{os.path.join(target_path, os.path.basename(path))}'

  return (f'{source_path}:{target_path}', f'{data_path}')


def main(argv):
  if len(argv) > 1:
    raise app.UsageError('Too many command-line arguments.')

  # You can individually override the following paths if you have placed the
  # data in locations other than the FLAGS.data_dir.

  # Path to the Uniref90 database for use by JackHMMER.
  uniref90_database_path = os.path.join(
      FLAGS.data_dir, 'uniref90', 'uniref90.fasta')

  # Path to the Uniprot database for use by JackHMMER.
  uniprot_database_path = os.path.join(
      FLAGS.data_dir, 'uniprot', 'uniprot.fasta')

  # Path to the MGnify database for use by JackHMMER.
  mgnify_database_path = os.path.join(
      FLAGS.data_dir, 'mgnify', 'mgy_clusters_2022_05.fa')

  # Path to the BFD database for use by HHblits.
  bfd_database_path = os.path.join(
      FLAGS.data_dir, 'bfd',
      'bfd_metaclust_clu_complete_id30_c90_final_seq.sorted_opt')

  # Path to the Small BFD database for use by JackHMMER.
  small_bfd_database_path = os.path.join(
      FLAGS.data_dir, 'small_bfd', 'bfd-first_non_consensus_sequences.fasta')

  # Path to the Uniref30 database for use by HHblits.
  uniref30_database_path = os.path.join(
      FLAGS.data_dir, 'uniref30', 'UniRef30_2021_03')

  # Path to the PDB70 database for use by HHsearch.
  pdb70_database_path = os.path.join(FLAGS.data_dir, 'pdb70', 'pdb70')

  # Path to the PDB seqres database for use by hmmsearch.
  pdb_seqres_database_path = os.path.join(
      FLAGS.data_dir, 'pdb_seqres', 'pdb_seqres.txt')

  # Path to a directory with template mmCIF structures, each named <pdb_id>.cif.
  template_mmcif_dir = os.path.join(FLAGS.data_dir, 'pdb_mmcif', 'mmcif_files')

  # Path to a file mapping obsolete PDB IDs to their replacements.
  obsolete_pdbs_path = os.path.join(FLAGS.data_dir, 'pdb_mmcif', 'obsolete.dat')

  alphafold_path = pathlib.Path(__file__).parent.parent
  data_dir_path = pathlib.Path(FLAGS.data_dir)
  if alphafold_path == data_dir_path or alphafold_path in data_dir_path.parents:
    raise app.UsageError(
        f'The download directory {FLAGS.data_dir} should not be a subdirectory '
        f'in the AlphaFold repository directory. If it is, the Singularity build is '
        f'slow since the large databases are copied during the image creation.')

  binds = []
  command_args = []

  # Mount each fasta path as a unique target directory.
  target_fasta_paths = []
  for i, fasta_path in enumerate(FLAGS.fasta_paths):
    bind, target_path = _create_bind(f'fasta_path_{i}', fasta_path)
    binds.append(bind)
    target_fasta_paths.append(target_path)
  command_args.append(f'--fasta_paths={",".join(target_fasta_paths)}')

  database_paths = [
      ('uniref90_database_path', uniref90_database_path),
      ('mgnify_database_path', mgnify_database_path),
      ('data_dir', FLAGS.data_dir),
      ('template_mmcif_dir', template_mmcif_dir),
      ('obsolete_pdbs_path', obsolete_pdbs_path),
  ]

  if FLAGS.model_preset == 'multimer':
    database_paths.append(('uniprot_database_path', uniprot_database_path))
    database_paths.append(('pdb_seqres_database_path',
                           pdb_seqres_database_path))
  else:
    database_paths.append(('pdb70_database_path', pdb70_database_path))

  if FLAGS.db_preset == 'reduced_dbs':
    database_paths.append(('small_bfd_database_path', small_bfd_database_path))
  else:
    database_paths.extend([
        ('uniref30_database_path', uniref30_database_path),
        ('bfd_database_path', bfd_database_path),
    ])

  # NB for binds:
  #    - first arg = path on host
  #    - second arg = path in container
  for name, path in database_paths:
    if path:
      bind, target_path = _create_bind(name, path)
      binds.append(bind)
      command_args.append(f'--{name}={target_path}')

  output_target_path = os.path.join(_ROOT_MOUNT_DIRECTORY, 'output')
  binds.append(f'{FLAGS.output_dir}:{output_target_path}')
  logging.info('Binding %s -> %s', FLAGS.output_dir, output_target_path)

  tmp_target_path = '/tmp'
  binds.append(f'{tmp_dir}:{tmp_target_path}')
  logging.info('Binding %s -> %s', tmp_dir, tmp_target_path)

  use_gpu_relax = FLAGS.enable_gpu_relax and FLAGS.use_gpu

  command_args.extend([
      f'--output_dir={output_target_path}',
      f'--max_template_date={FLAGS.max_template_date}',
      f'--db_preset={FLAGS.db_preset}',
      f'--model_preset={FLAGS.model_preset}',
      f'--benchmark={FLAGS.benchmark}',
      f'--use_precomputed_msas={FLAGS.use_precomputed_msas}',
      f'--num_multimer_predictions_per_model={FLAGS.num_multimer_predictions_per_model}',
      f'--models_to_relax={FLAGS.models_to_relax}',
      f'--use_gpu_relax={use_gpu_relax}',
      '--logtostderr',
  ])

  options = [
    '--bind', f'{",".join(binds)}',
    '--env', f'NVIDIA_VISIBLE_DEVICES={FLAGS.gpu_devices}',
    # The following flags allow us to make predictions on proteins that
    # would typically be too long to fit into GPU memory.
    '--env', 'TF_FORCE_UNIFIED_MEMORY=1',
    '--env', 'XLA_PYTHON_CLIENT_MEM_FRACTION=4.0',
  ]

  # Run the container.
  # Result is a dict with keys "message" (value = all output as a single string),
  # and "return_code" (value = integer return code)
  result = Client.run(
             singularity_image,
             command_args,
             nv=True if FLAGS.use_gpu else None,
             return_result=True,
             options=options
           )


if __name__ == '__main__':
  flags.mark_flags_as_required([
      'data_dir',
      'fasta_paths',
      'max_template_date',
  ])
  app.run(main)

[1] DeepMind: AlphaFold official website

[2] Official AlphaFold repository at Github

[3] Jumper, J., Evans, R., Pritzel, A. et al. Highly accurate protein structure prediction with AlphaFold. Nature 596, 583–589 (2021).