Levk: Created page with "'''AlphaFold3 Module Guide''' == Overview == This guide provides instructions on using the AlphaFold3 module in an HPC environment with Slurm and Apptainer (Singularity). ==..."

2025-03-20T12:13:12Z

Created page with "'''AlphaFold3 Module Guide''' == Overview == This guide provides instructions on using the AlphaFold3 module in an HPC environment with Slurm and Apptainer (Singularity). ==..."

New page

'''AlphaFold3 Module Guide'''

== Overview ==
This guide provides instructions on using the AlphaFold3 module in an HPC environment with Slurm and Apptainer (Singularity).

== Loading the Module ==
To use AlphaFold3, first load the module:
<syntaxhighlight lang="bash">
module load alphafold3
</syntaxhighlight>
This will automatically load the required Apptainer module and set up necessary environment variables.

== Environment Variables ==
After loading the module, the following environment variables are available:
* '''$AF3_CONTAINER''' - Path to the AlphaFold3 Singularity container
* '''$AF3_MODELS''' - Path to AlphaFold3 model parameters
* '''$AF3_DB''' - Path to the AlphaFold3 database
* '''$AF3_SRC''' - Path to AlphaFold3 source directory

== Understanding Bind Mounts in Singularity ==
Singularity requires **bind mounts** to provide external directories inside the container. This ensures that the container can access necessary files without modifying its internal structure.

A bind mount follows this format:
<syntaxhighlight lang="bash">
--bind /path/on/host:/path/inside/container
</syntaxhighlight>
- `/path/on/host` → The folder on your actual system (outside the container)
- `/path/inside/container` → Where this folder will be accessible **inside** the container

For example:
<syntaxhighlight lang="bash">
--bind /home/user/data:/root/input_data
</syntaxhighlight>
This allows the **`/home/user/data`** directory on the host system to appear inside the container at **`/root/input_data`**.

== Binding a Folder for Your Input Data ==
The default AlphaFold3 example from Google DeepMind uses `/root/af_input`, but this is **not a required folder inside the container**. You can bind your input folder to **any directory** inside the container.

For example, if your input JSON is located at `/home/user/alphafold_inputs/fold_input.json`, you can bind it inside the container at **any location**:
<syntaxhighlight lang="bash">
--bind /home/user/alphafold_inputs:/root/custom_folder
</syntaxhighlight>
Then, the JSON file should be referenced as:
<syntaxhighlight lang="bash">
--json_path=/root/custom_folder/fold_input.json
</syntaxhighlight>

Refer to the official AlphaFold3 documentation for details on how to structure the input file: [AlphaFold3 Input File Guide](https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md)

== Listing All Available Command Flags ==
To see a full list of available command-line options for AlphaFold3, run the following inside the container:
<syntaxhighlight lang="bash">
singularity exec --nv \
--bind $AF3_SRC:/root/custom_folder \
--bind /tmp:/root/af_output \
--bind $AF3_MODELS:/root/models \
--bind $AF3_DB:/root/public_databases \
--bind /home/user/alphafold_inputs:/root/custom_folder \
$AF3_CONTAINER \
python /root/custom_folder/run_alphafold.py --helpfull
</syntaxhighlight>
This will provide detailed documentation on all possible flags and parameters that can be used when running AlphaFold3.

== Running AlphaFold3 ==
To run AlphaFold3 inside the Singularity container, use:
<syntaxhighlight lang="bash">
singularity exec --nv \
--bind $AF3_SRC:/root/custom_folder \
--bind /tmp:/root/af_output \
--bind $AF3_MODELS:/root/models \
--bind $AF3_DB:/root/public_databases \
--bind /home/user/alphafold_inputs:/root/custom_folder \
$AF3_CONTAINER \
python /root/custom_folder/run_alphafold.py \
--json_path=/root/custom_folder/fold_input.json \
--model_dir=/root/models \
--db_dir=/root/public_databases \
--output_dir=/root/af_output
</syntaxhighlight>

Replace `/home/user/alphafold_inputs` with the actual path to your input folder.

== Binding a Folder That is Not Related to Built-In Environment Variables ==
If you need to bind a folder that is **not already covered by** `$AF3_SRC`, `$AF3_DB`, or `$AF3_MODELS`, you can specify it manually using the `--bind` option. Example:
<syntaxhighlight lang="bash">
--bind /external/data:/root/custom_data
</syntaxhighlight>
This makes `/external/data` accessible inside the container at `/root/custom_data`.

Then, reference files from inside the container:
<syntaxhighlight lang="bash">
--json_path=/root/custom_data/my_input.json
</syntaxhighlight>

== Submitting an AlphaFold3 Job to Slurm ==
To submit an AlphaFold3 job to Slurm, create a script (e.g., `alphafold3_job.sh`):
<syntaxhighlight lang="bash">
#!/bin/bash
#SBATCH --job-name=alphafold3
#SBATCH --partition=gpu-general
#SBATCH --output=alphafold3.out
#SBATCH --error=alphafold3.err
#SBATCH --gres=gpu:1,af3
#SBATCH --cpus-per-task=8
#SBATCH --mem=64G
#SBATCH --time=1-00:00:00

module load alphafold3

singularity exec --nv \
--bind $AF3_SRC:/root/custom_folder \
--bind /tmp:/root/af_output \
--bind $AF3_MODELS:/root/models \
--bind $AF3_DB:/root/public_databases \
--bind /home/user/alphafold_inputs:/root/custom_folder \
$AF3_CONTAINER \
python /root/custom_folder/run_alphafold.py \
--json_path=/root/custom_folder/fold_input.json \
--model_dir=/root/models \
--db_dir=/root/public_databases \
--output_dir=/root/af_output
</syntaxhighlight>

Submit the job using:
<syntaxhighlight lang="bash">
sbatch alphafold3_job.sh
</syntaxhighlight>

== Unloading the Module ==
To unload the module when done:
<syntaxhighlight lang="bash">
module unload alphafold3
</syntaxhighlight>

This will also unload the Apptainer module.

== Troubleshooting ==
* If the module does not load, ensure the correct name is used: `module avail alphafold3`
* If Slurm fails to allocate a node, check available resources: `sinfo -o "%N %G"`
* If the container fails to run, verify that the paths in `$AF3_CONTAINER`, `$AF3_MODELS`, and `$AF3_DB` are correct.
* If input files are not found, ensure the correct directory is bound and referenced properly inside the container.

Alphafold3 - Revision history

Levk: Created page with "'''AlphaFold3 Module Guide''' == Overview == This guide provides instructions on using the AlphaFold3 module in an HPC environment with Slurm and Apptainer (Singularity). ==..."