AlphaFold3¶

Overview¶

AlphaFold3 represents a significant advancement in computational structural biology, extending beyond protein folding to predict the structures of entire biomolecular complexes. This third iteration from DeepMind can model proteins, nucleic acids (DNA and RNA), small molecules, ions, and their interactions with high accuracy.

On the Hyperion cluster, AlphaFold3 is deployed as an optimized Apptainer container, providing researchers with access to this technology while ensuring reproducibility and efficient resource utilization.

Getting started¶

Environment modules¶

The AlphaFold3 installation on Hyperion uses the Lmod module system. Loading the module automatically configures all necessary paths and dependencies.

module load AlphaFold/3.0.1

This command sets up your environment with:

• The AlphaFold3 container path
• Access to model weights (neural network parameters)
• Reference databases (UniRef90, PDB, and RNA sequences)
• Optimized wrapper scripts for simplified execution
• Automatic Apptainer module loading

Module environment variables¶

Available commands¶

Verifying the environment¶

Before running your first prediction, verify that everything is properly configured:

module load AlphaFold/3.0.1
alphafold3-check

======================================
AlphaFold3 Installation Check
======================================

Environment Variables:
----------------------
AF3_CONTAINER: <location of the container file>
AF3_WEIGHTS:   <location of neural network parameters>
AF3_DB:        <location of reference sequence database>

Component Status:
-----------------
✓ Container found (2.8G)
✓ Model weights found (1.1G)
✓ Database directory found (10 files)

Key Database Files:
  ✓ uniref90_2022_05.fa
  ✓ pdb_seqres_2022_09_28.fasta
  ✓ bfd-first_non_consensus_sequences.fasta

GPU Status:
-----------
✓ GPU detected: NVIDIA A100-SXM4-80GB, 81920 MiB
  CUDA_VISIBLE_DEVICES: 0

SLURM Context:
--------------
Job ID: 3209670
Partition: preemption
QOS: regular
CPUs: 1
Memory: 204800

Container Test:
---------------
Testing container execution...
Python OK
✓ Container execution successful

======================================
Check complete

Quick start guide¶

Interactive session¶

For development and testing, interactive sessions provide immediate feedback:

# Request GPU resources for 2 hours
srun --gres=gpu:1 --mem=100G --partition=general --qos=regular --pty bash

# Load the AlphaFold3 module
module load AlphaFold/3.0.1

# Run your prediction
alphafold3-run input.json output_dir/

Batch submission¶

For production runs, submit jobs through SLURM:

#!/bin/bash
#SBATCH --job-name=af3_prediction
#SBATCH --partition=general
#SBATCH --qos=regular
#SBATCH --gres=gpu:1
#SBATCH --constraint=a100-pcie
#SBATCH --cpus-per-task=48
#SBATCH --mem=100GB
#SBATCH --output=%x_%j.out
#SBATCH --error=%x_%j.err

module load AlphaFold/3.0.1

# Your input file and output directory
alphafold3-run complex_input.json results_${SLURM_JOB_ID}/

Input format specification¶

AlphaFold3 uses JSON files to define molecular systems for prediction. This section covers the essential input format requirements.

Basic structure¶

Every AlphaFold3 input requires five mandatory fields:

{
  "name": "my_prediction",
  "sequences": [
    {
      "protein": {
        "id": ["A"],
        "sequence": "MAFSAEDVLK..."
      }
    }
  ],
  "modelSeeds": [1, 2, 3],
  "dialect": "alphafold3",
  "version": 1
}

Molecular entity types¶

Proteins¶

{
  "protein": {
    "id": ["A"],
    "sequence": "MAFSAEDVLKEYDRRRM..."
  }
}

• id: Chain identifier(s). Use ["A", "B"] for homodimers
• sequence: Standard single-letter amino acid codes

Nucleic acids¶

{
  "rna": {
    "id": ["R"],
    "sequence": "AUGCAUGC"
  }
}

{
  "dna": {
    "id": ["D"],
    "sequence": "ATGCATGC"
  }
}

Ligands¶

{
  "ligand": {
    "id": ["L"],
    "smiles": "CC(C)CC1=CC=C(C=C1)C(C)C(=O)O"
  }
}

{
  "ligand": {
    "id": ["L"],
    "ccdCodes": ["ATP"]
  }
}

Ions¶

{
  "ion": {
    "id": ["I"],
    "ccdCodes": ["MG"]
  }
}

Common ion codes: MG (magnesium), ZN (zinc), CA (calcium), FE (iron)

Complete examples¶

{
  "name": "GLUT1_glucose_complex",
  "sequences": [
    {
      "protein": {
        "id": ["A"],
        "sequence": "MEPSDKDKKE..."
      }
    },
    {
      "ligand": {
        "id": ["B"],
        "smiles": "C([C@@H]1[C@H]([C@@H]([C@H](C(O1)O)O)O)O)O"
      }
    }
  ],
  "modelSeeds": [1, 2, 3],
  "dialect": "alphafold3",
  "version": 1
}

{
  "name": "zinc_finger_DNA",
  "sequences": [
    {
      "protein": {
        "id": ["A"],
        "sequence": "MTCPECGE..."
      }
    },
    {
      "dna": {
        "id": ["D"],
        "sequence": "GCGTGGGCG"
      }
    },
    {
      "ion": {
        "id": ["Z"],
        "ccdCodes": ["ZN"]
      }
    }
  ],
  "modelSeeds": [1, 2, 3, 4, 5],
  "dialect": "alphafold3",
  "version": 1
}

Format conversion¶

MOL2 and SDF formats are not directly supported. Convert to SMILES:

obabel input.mol2 -O output.smi

from rdkit import Chem

# From MOL2
mol = Chem.MolFromMol2File('input.mol2')
smiles = Chem.MolToSmiles(mol)
print(smiles)

# From SDF
suppl = Chem.SDMolSupplier('input.sdf')
for mol in suppl:
    smiles = Chem.MolToSmiles(mol)
    print(smiles)

Advanced features¶

For advanced use cases, consult the official documentation:

AlphaFold3 Input Format Documentation →

Advanced topics include:

• Post-translational modifications (phosphorylation, glycosylation)
• Covalent bond specifications between entities
• Custom MSA and template provision
• User-defined chemical components
• Chain stoichiometry and multiple copies

Understanding resource requirements¶

GPU selection strategy¶

AlphaFold3's memory requirements depend on the size of your molecular system. The Hyperion cluster provides two GPU types, each suited for different scales:

#SBATCH --gres=gpu:1
#SBATCH --constraint=rtx3090
#SBATCH --mem=32G

#SBATCH --gres=gpu:1
#SBATCH --constraint=rtx3090
#SBATCH --mem=48G

#SBATCH --gres=gpu:1
#SBATCH --constraint=a100-pcie
#SBATCH --mem=64G

#SBATCH --gres=gpu:1
#SBATCH --constraint=a100-pcie
#SBATCH --mem=128G

Token calculation¶

Understanding token counts is crucial for resource planning:

Memory considerations¶

AlphaFold3 uses memory in two critical phases:

1. MSA Generation (CPU-intensive): Searches sequence databases to find evolutionary related sequences
2. Structure Inference (GPU-intensive): Predicts 3D coordinates using the neural network

Job submission templates¶

Standard single job¶

#!/bin/bash
#SBATCH --job-name=af3_protein
#SBATCH --partition=general
#SBATCH --qos=regular
#SBATCH --gres=gpu:1
#SBATCH --constraint=a100-pcie
#SBATCH --cpus-per-task=48
#SBATCH --mem=100GB
#SBATCH --output=logs/%x_%j.out
#SBATCH --error=logs/%x_%j.err

# Create output directories
mkdir -p logs

# Load AlphaFold3
module load AlphaFold/3.0.1

# Define paths
INPUT_JSON="input.json"
OUTPUT_DIR="af3_output_${SLURM_JOB_ID}"

# Run prediction
alphafold3-run ${INPUT_JSON} ${OUTPUT_DIR}

# Report completion
if [ $? -eq 0 ]; then
    echo "Successfully completed at $(date)"
    echo "Results saved to: ${OUTPUT_DIR}"
else
    echo "Prediction failed - check error logs"
fi

Array jobs for high-throughput screening¶

Process multiple structures efficiently with array jobs:

#!/bin/bash
#SBATCH --job-name=af3_array
#SBATCH --partition=general
#SBATCH --qos=regular
#SBATCH --gres=gpu:1
#SBATCH --constraint=a100-pcie
#SBATCH --cpus-per-task=48
#SBATCH --mem=100GB
#SBATCH --array=1-10%2    # Process 10 structures, max 2 concurrent
#SBATCH --output=logs/array_%A_%a.out
#SBATCH --error=logs/array_%A_%a.err

module load AlphaFold/3.0.1

# Directory structure for array jobs
INPUT_DIR="inputs"
OUTPUT_DIR="outputs"

# Each array task processes one input file
INPUT_FILE="${INPUT_DIR}/input_${SLURM_ARRAY_TASK_ID}.json"
JOB_OUTPUT="${OUTPUT_DIR}/job_${SLURM_ARRAY_TASK_ID}"

mkdir -p ${JOB_OUTPUT}

echo "Processing structure ${SLURM_ARRAY_TASK_ID} of ${SLURM_ARRAY_SIZE}"
alphafold3-run ${INPUT_FILE} ${JOB_OUTPUT}

Understanding the wrapper script¶

How the wrapper works¶

The alphafold3-run wrapper script abstracts the complexity of container execution.

alphafold3-run input.json output/

apptainer exec --nv \
    --bind ${AF3_WEIGHTS}:/root/models:ro \
    --bind ${AF3_DB}:/root/public_databases:ro \
    --bind $(pwd):/work \
    --pwd /work \
    ${AF3_CONTAINER} \
    python /app/alphafold/run_alphafold.py \
    --json_path=input.json \
    --output_dir=output \
    --db_dir=/root/public_databases \
    --model_dir=/root/models

The wrapper handles:

• Container GPU enablement (--nv flag)
• Read-only mounting of databases and weights
• Working directory binding
• Path translations between host and container

Direct container usage¶

For advanced users needing custom parameters:

module load AlphaFold/3.0.1

# Direct execution with custom options
apptainer exec --nv \
    --bind ${AF3_WEIGHTS}:/root/models:ro \
    --bind ${AF3_DB}:/root/public_databases:ro \
    --bind $(pwd):/work \
    --pwd /work \
    ${AF3_CONTAINER} \
    python /app/alphafold/run_alphafold.py \
    --json_path=input.json \
    --output_dir=output \
    --db_dir=/root/public_databases \
    --model_dir=/root/models \
    --num_diffusion_samples=5 \
    --flash_attention_implementation=triton \
    --buckets=256,512,768,1024,1280,1536,2048

Performance optimization¶

Automatic GPU configuration¶

Manual environment variables¶

# Conservative memory usage for 24GB VRAM
export APPTAINERENV_XLA_PYTHON_CLIENT_PREALLOCATE=false
export APPTAINERENV_XLA_PYTHON_CLIENT_MEM_FRACTION=0.85
export APPTAINERENV_TF_FORCE_GPU_ALLOW_GROWTH=true

# Maximum performance for 40/80GB VRAM
export APPTAINERENV_XLA_PYTHON_CLIENT_PREALLOCATE=true
export APPTAINERENV_XLA_PYTHON_CLIENT_MEM_FRACTION=0.95

# For very large systems
export APPTAINERENV_CUDA_MANAGED_FORCE_DEVICE_ALLOC=1

JAX compilation cache¶

Reduce startup time significantly by caching compiled kernels:

# Add to your SLURM script
export JAX_COMPILATION_CACHE_DIR=/scratch/$USER/.jax_cache
mkdir -p $JAX_COMPILATION_CACHE_DIR

Optimization strategies¶

Output structure and files¶

Directory organization¶

AlphaFold3 creates a structured output directory with all prediction results:

output_dir/
├── <job_name>_model_0.cif          # Structure from seed 1
├── <job_name>_model_1.cif          # Structure from seed 2
├── <job_name>_model_2.cif          # Structure from seed 3
├── <job_name>_confidences.json     # Confidence metrics
├── <job_name>_summary_confidences.json  # Prediction summary
└── <job_name>_data.json            # Complete prediction data

File descriptions¶

Storage planning¶

Troubleshooting guide¶

Common issues and solutions¶

RuntimeError: Resource exhausted: Out of memory

slurmstepd: error: Detected 1 oom-kill event(s)

#SBATCH --mem=200GB  # Generous allocation for large systems

RuntimeError: No CUDA GPUs are available

ValueError: AlphaFold 3 input JSON must contain `dialect` and `version` fields

{
  "name": "my_protein",
  "sequences": [...],
  "modelSeeds": [1, 2, 3],
  "dialect": "alphafold3",  // Must be exactly "alphafold3"
  "version": 1              // Integer, not string
}

python -m json.tool input.json  # Checks JSON syntax

Data management best practices¶

Efficient scratch usage¶

The /scratch filesystem provides fast temporary storage ideal for AlphaFold3 runs:

# Recommended workflow
SCRATCH_DIR="/scratch/$USER/af3_runs/${SLURM_JOB_ID}"
mkdir -p ${SCRATCH_DIR}
cd ${SCRATCH_DIR}

# Run prediction in scratch
alphafold3-run input.json output/

# Move only essential results to permanent storage
rsync -av output/*.cif output/*_confidence*.json /home/$USER/af3_results/

# Cleanup scratch
rm -rf ${SCRATCH_DIR}

Storage guidelines¶

Quick reference¶

Essential information card¶

module load AlphaFold/3.0.1

alphafold3-run input.json output/

{
  "name": "job_name",
  "sequences": [...],
  "modelSeeds": [1,2,3],
  "dialect": "alphafold3",
  "version": 1
}

Confidence interpretation¶

Understanding AlphaFold3's confidence metrics is crucial for interpreting results:

Additional resources¶

External links¶

• AlphaFold3 Paper - Original Nature publication
• GitHub Repository - Source code and updates
• Input Format Documentation - Complete JSON specification
• AlphaFold Database - Pre-computed structures
• ChimeraX Tutorials - Visualization guides