ccervantess/beastx-beagle-cuda repository overview

⁠BEAST X + BEAGLE CUDA en Docker/Apptainer

Este repositorio contiene imágenes de contenedor para BEAST X junto con BEAGLE, compilado con soporte CUDA, para ejecutar análisis filogenéticos bayesianos aprovechando aceleración por GPU.

BEAST X es la continuación de BEAST v1.x y permite realizar inferencia filogenética bayesiana mediante MCMC, incluyendo análisis con relojes moleculares, estimación de árboles fechados, modelos de sustitución molecular y otros modelos evolutivos.

BEAGLE es una biblioteca de alto rendimiento que acelera el cálculo de verosimilitudes filogenéticas y permite utilizar procesadores paralelos, incluyendo GPUs NVIDIA.

Las imágenes están pensadas para facilitar el uso de BEAST X + BEAGLE en servidores, estaciones de trabajo y ambientes HPC mediante Docker o Apptainer.

⁠Imagen probada en GPU

Esta imagen fue probada exitosamente en una GPU:

NVIDIA Tesla V100-PCIE-32GB

La prueba confirmó que BEAST detecta BEAGLE y que BEAGLE reconoce la GPU como recurso CUDA:

BEAGLE resources available:
0 : CPU
1 : Tesla V100-PCIE-32GB
    Flags: ... PROCESSOR_GPU FRAMEWORK_CUDA ...

⁠Versiones incluidas

La imagen contiene:

BEAST X v10.5.0
BEAGLE v4.0.1
CUDA Toolkit 12.4.1
OpenJDK 17

BEAGLE fue compilado con soporte CUDA y arquitectura:

sm_70

Esta arquitectura corresponde a GPUs NVIDIA Volta, como la Tesla V100.

⁠Versiones disponibles

Cada etiqueta del repositorio corresponde a una combinación específica de BEAST X, BEAGLE y CUDA. Por ejemplo:

ccervantess/beastx-beagle-cuda:10.5.0-beagle4.0.1-cuda12.4

También puede existir una etiqueta:

ccervantess/beastx-beagle-cuda:latest

Para análisis reproducibles se recomienda usar siempre etiquetas específicas y evitar depender exclusivamente de latest.

⁠Programas incluidos

La imagen incluye las herramientas principales de BEAST X:

beast
beastx
beauti
treeannotator
logcombiner

También incluye un script de diagnóstico:

test_beagle_gpu

Este script permite verificar rápidamente si la imagen detecta NVIDIA-SMI, BEAGLE y los recursos GPU disponibles.

⁠Uso con Docker

Verificar que BEAST detecta BEAGLE y la GPU:

docker run --rm --gpus all \
  ccervantess/beastx-beagle-cuda:10.5.0-beagle4.0.1-cuda12.4 \
  -beagle_info

Ejecutar el diagnóstico completo:

docker run --rm --gpus all \
  --entrypoint test_beagle_gpu \
  ccervantess/beastx-beagle-cuda:10.5.0-beagle4.0.1-cuda12.4

Ejecutar un análisis con un archivo XML de BEAST:

docker run --rm --gpus all \
  -v "$PWD":/data \
  -w /data \
  ccervantess/beastx-beagle-cuda:10.5.0-beagle4.0.1-cuda12.4 \
  -beagle_GPU \
  -beagle_order 1 \
  -beagle_double \
  -threads 4 \
  analisis.xml

⁠Uso con Apptainer

Descargar la imagen desde Docker Hub:

apptainer pull beastx_beagle_cuda12_v100.sif \
  docker://ccervantess/beastx-beagle-cuda:10.5.0-beagle4.0.1-cuda12.4

Verificar que BEAST detecta BEAGLE:

apptainer exec --nv beastx_beagle_cuda12_v100.sif \
  beast -beagle_info

Ejecutar el diagnóstico completo:

apptainer exec --nv beastx_beagle_cuda12_v100.sif \
  test_beagle_gpu

Ejecutar un análisis con GPU:

apptainer exec --nv beastx_beagle_cuda12_v100.sif \
  beast \
  -beagle_GPU \
  -beagle_order 1 \
  -beagle_double \
  -threads 4 \
  analisis.xml

⁠Opciones comunes de BEAGLE

Usar GPU:

-beagle_GPU

Indicar el recurso GPU a usar:

-beagle_order 1

Usar precisión doble:

-beagle_double

Usar precisión simple:

-beagle_single

Mostrar los recursos BEAGLE disponibles:

-beagle_info

En muchos sistemas, el recurso 0 corresponde a CPU y el recurso 1 corresponde a la primera GPU detectada por BEAGLE.

⁠Ejemplo en Slurm con Apptainer

Ejemplo de script para ejecutar BEAST X + BEAGLE en una GPU NVIDIA V100:

#!/bin/bash
#SBATCH --job-name=beast_v100
#SBATCH --partition=gpu_V100
#SBATCH --gres=gpu:1
#SBATCH --cpus-per-task=4
#SBATCH --mem=16G
#SBATCH --time=5-00:00:00
#SBATCH --output=beast_v100_%j.out
#SBATCH --error=beast_v100_%j.err

SIF=$HOME/beastx_beagle_cuda12_v100.sif
XML=$1

echo "Nodo:"
hostname

echo "GPU asignada:"
nvidia-smi

echo "Recursos BEAGLE:"
apptainer exec --nv "$SIF" beast -beagle_info

echo "Iniciando BEAST X con BEAGLE GPU..."

apptainer exec --nv "$SIF" \
  beast \
  -beagle_GPU \
  -beagle_order 1 \
  -beagle_double \
  -threads "$SLURM_CPUS_PER_TASK" \
  "$XML"

Enviar el trabajo:

sbatch run_beast_gpu.slurm analisis.xml

⁠Notas importantes

Para usar GPU con Apptainer es necesario ejecutar el contenedor con:

--nv

Sin esta opción, el contenedor puede ejecutarse, pero no tendrá acceso a las GPUs NVIDIA del sistema.

Para usar GPU con Docker es necesario contar con NVIDIA Container Toolkit y ejecutar la imagen con:

--gpus all

Aunque el sistema anfitrión muestre una versión de CUDA más reciente mediante nvidia-smi, la imagen utiliza CUDA Toolkit 12.4.1 internamente. Esto permite mantener compatibilidad con GPUs Tesla V100.

⁠Reproducibilidad

Para análisis reproducibles se recomienda indicar explícitamente la etiqueta usada, por ejemplo:

ccervantess/beastx-beagle-cuda:10.5.0-beagle4.0.1-cuda12.4

La etiqueta latest, si existe, puede cambiar con el tiempo.

⁠Mantenedor

Cristian Cervantes Unidad de Síntesis en Sistemática y Evolución Instituto de Biología Universidad Nacional Autónoma de México

⁠Licencia

Este contenedor integra software de terceros. Cada programa conserva su propia licencia. Se recomienda revisar las licencias individuales de BEAST X, BEAGLE, CUDA, OpenJDK y las bibliotecas incluidas antes de su redistribución o uso en producción.