AlphaFold3: advanced usage¶

This page covers advanced topics for AlphaFold3 on Hyperion. For basic setup and job submission, see the main AlphaFold3 page.

Complex input examples¶

Protein-ligand complex¶

{
  "name": "GLUT1_glucose",
  "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
}

Protein-DNA complex with metal ion¶

{
  "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
}

Ligand format conversion¶

AlphaFold3 accepts ligands as SMILES strings or CCD codes. To convert from MOL2 or SDF:

obabel input.mol2 -O output.smi

from rdkit import Chem

mol = Chem.MolFromMol2File("input.mol2")
print(Chem.MolToSmiles(mol))

For post-translational modifications, covalent bond specifications, custom MSAs, and user-defined chemical components, see the official input format documentation.

Array jobs for screening¶

Process multiple structures with SLURM array jobs. Place your input files as inputs/input_1.json, inputs/input_2.json, etc.:

#!/bin/bash
#SBATCH --qos=regular
#SBATCH --job-name=af3_screen
#SBATCH --partition=general
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=48
#SBATCH --mem=100G
#SBATCH --gpus=1
#SBATCH --time=12:00:00
#SBATCH --array=1-10%2
#SBATCH --output=logs/af3_%A_%a.out
#SBATCH --error=logs/af3_%A_%a.err

module load AlphaFold/3.0.1

mkdir -p logs

alphafold3-run inputs/input_${SLURM_ARRAY_TASK_ID}.json \
    outputs/run_${SLURM_ARRAY_TASK_ID}/

The %2 suffix limits concurrency to 2 simultaneous GPU jobs. Adjust based on GPU availability.

Direct container usage¶

The alphafold3-run wrapper handles container execution automatically. If you need custom flags (e.g., diffusion samples, flash attention), invoke the container directly:

module load AlphaFold/3.0.1

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 tuning¶

JAX compilation cache¶

AlphaFold3 compiles JAX kernels on first run, which takes 10-15 minutes. Cache them to skip this on subsequent runs:

export JAX_COMPILATION_CACHE_DIR=/scratch/$USER/.jax_cache
mkdir -p $JAX_COMPILATION_CACHE_DIR

Add these lines to your batch scripts. The cache persists across jobs and can be shared within a research group.

GPU memory configuration¶

The module auto-detects your GPU and sets optimal memory parameters. To override manually, use the APPTAINERENV_ prefix so variables reach the container:

export APPTAINERENV_XLA_PYTHON_CLIENT_PREALLOCATE=false
export APPTAINERENV_XLA_PYTHON_CLIENT_MEM_FRACTION=0.85
export APPTAINERENV_TF_FORCE_GPU_ALLOW_GROWTH=true

export APPTAINERENV_XLA_PYTHON_CLIENT_PREALLOCATE=true
export APPTAINERENV_XLA_PYTHON_CLIENT_MEM_FRACTION=0.95

MSA reuse¶

The MSA generation phase (CPU-intensive, 4-8 hours for large proteins) searches sequence databases for evolutionary information. If you are predicting multiple variants of the same protein, save the MSA output from the first run and provide it as a custom MSA in subsequent runs to skip this step. See the input format documentation for the custom MSA fields.

Interpreting confidence scores¶

AlphaFold3 reports per-residue confidence (pLDDT) in the output JSON:

The Predicted Aligned Error (PAE) matrix in _confidences.json indicates the relative position confidence between all residue pairs. Low PAE between domains suggests a confident inter-domain arrangement; high PAE suggests the relative orientation is uncertain even if individual domains are well-predicted.

See also¶