====== Utilisation d'Apptainer ======

Cette page décrit comment utiliser Apptainer pour faire tourner un programme C
utilisant la bibliothèque OpenBLAS sur le cluster. Elle couvre la création de
l'image conteneur, sa construction sur votre machine personnelle, son transfert
sur le cluster, et la soumission d'un job Slurm.

OpenBLAS n'étant pas installé sur les nœuds de calcul, Apptainer permet d'embarquer
la bibliothèque dans une image portable et de l'utiliser sans intervention de
l'administrateur système.

===== Prérequis =====

  * Avoir Apptainer installé sur sa machine Linux personnelle (voir [[https://apptainer.org/docs/user/latest/quick_start.html|documentation officielle]])


===== 1. Créer le fichier de définition (.def) =====

Le fichier `.def` est la recette de construction du conteneur. Il décrit le système
de base et les logiciels à installer. Pour cet exemple on souhaite un conteneur qui peut compiler et faire tourner un code qui nécessite la bibliothèque OpenBLAS.

Créez un fichier ''openblas.def'' sur votre machine personnelle.

==== Option A — Installation via les paquets Ubuntu (recommandée) ====

Simple et rapide. Utilise la version d'OpenBLAS fournie par Ubuntu.

<code>
Bootstrap: docker
From: ubuntu:24.04

%post
    apt-get update -y
    apt-get install -y gcc-13 libopenblas-dev

%environment
    export LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH

</code>

==== Option B — Compilation d'OpenBLAS depuis les sources ====

Recommandée si vous souhaitez contrôler précisément les options de compilation
(optimisations CPU, support multithread, etc.), ou que votre bibliothèque n'est pas dans les packages standard.

<code>
Bootstrap: docker
From: ubuntu:24.04

%post
    apt-get update -y
    apt-get install -y gcc-13 make wget tar

    cd /tmp
    wget https://github.com/OpenMathLib/OpenBLAS/releases/download/v0.3.26/OpenBLAS-0.3.26.tar.gz
    tar xzf OpenBLAS-0.3.26.tar.gz
    cd OpenBLAS-0.3.26
    make CC=gcc-13
    make PREFIX=/usr/local install

%environment
    export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
</code>



===== 2. Construire l'image sur sa machine personnelle =====

La construction de l'image nécessite les droits root. Elle doit donc être effectuée
sur votre machine personnelle (Linux), et non sur le cluster.

<code bash>
sudo apptainer build openblas.sif openblas.def
</code>

La construction prend quelques minutes. À l'issue, un fichier ''openblas.sif'' est créé.

<note>
Le fichier ''.sif'' est une image au format SquashFS — compressée, en lecture seule,
et totalement portable. Il contient un système Ubuntu complet avec GCC et OpenBLAS.
</note>

Vérifiez que l'image est correcte avant de la transférer :

<code bash>
apptainer exec openblas.sif gcc-13 --version
apptainer exec openblas.sif ls /usr/lib/x86_64-linux-gnu/libopenblas*
</code>
La première commande doit afficher la version de GCC, par exemple :
  gcc-13 (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0

La seconde doit afficher le chemin de la bibliothèque OpenBLAS, par exemple :
  /usr/lib/x86_64-linux-gnu/libopenblas.so
  /usr/lib/x86_64-linux-gnu/libopenblas.so.0

Si l'une des deux commandes retourne une erreur, l'image est incomplète —
recommencez la construction.
===== 3. Transférer l'image sur le cluster =====

Copiez l'image depuis votre machine personnelle vers votre répertoire de travail sur le cluster :

<code bash>
scp openblas.sif login@frontalhpc2025:
</code>

/*
<note warning>
Évitez de stocker les images ''.sif'' directement dans votre ''$HOME'' pour un usage
intensif en production. Préférez un espace de stockage rapide (scratch) si disponible.
Pour des tests ponctuels, le ''$HOME'' est suffisant.
</note>
*/

===== 4. Préparer le code source =====

Voici un exemple de programme C utilisant OpenBLAS (multiplication de matrices) :

<code c>
/* bench_dgemm.c */
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
#include <cblas.h>

#define N 8192

int main() {
    openblas_set_num_threads(1);

    double *A = malloc(N * N * sizeof(double));
    double *B = malloc(N * N * sizeof(double));
    double *C = calloc(N * N, sizeof(double));

    for (int i = 0; i < N * N; i++) {
        A[i] = (double)rand() / RAND_MAX;
        B[i] = (double)rand() / RAND_MAX;
    }

    struct timespec t0, t1;
    clock_gettime(CLOCK_MONOTONIC, &t0);

    cblas_dgemm(CblasRowMajor, CblasNoTrans, CblasNoTrans,
                N, N, N, 1.0, A, N, B, N, 0.0, C, N);

    clock_gettime(CLOCK_MONOTONIC, &t1);

    double elapsed = (t1.tv_sec - t0.tv_sec) +
                     (t1.tv_nsec - t0.tv_nsec) * 1e-9;
    double gflops = (2.0 * N * N * N) / elapsed / 1e9;

    printf("N=%d : %.3f s | %.2f GFLOPS\n", N, elapsed, gflops);

    free(A); free(B); free(C);
    return 0;
}
</code>

Placez ce fichier dans votre répertoire de travail sur le cluster :

<code bash>
~/mon_projet/bench_dgemm.c
</code>

===== 5. Soumettre le job Slurm =====

Créez le script de soumission ''bench_apptainer.sh'' :

<code bash>
#!/bin/bash
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=1

IMG=~/openblas.sif
SRC=~/mon_projet/bench_dgemm.c
BIN=~/mon_projet/bench_dgemm

# Compilation dans le conteneur
apptainer exec $IMG \
    gcc-13 -O3 -march=native -o $BIN $SRC \
    -I/usr/local/include \
    -L/usr/local/lib \
    -lopenblas \
    -Wl,-rpath,/usr/local/lib

# Exécution dans le conteneur
apptainer exec $IMG $BIN

</code>

<note tip>
Adaptez le chemin des includes et des libs selon l'option choisie :
  * **Option A** (paquets Ubuntu) : ''-I/usr/include'' et ''-L/usr/lib/x86_64-linux-gnu''
  * **Option B** (compilation depuis les sources) : ''-I/usr/local/include'' et ''-L/usr/local/lib''
</note>

Soumettez le job :

<code bash>
sbatch bench_apptainer.sh
</code>


Ensuite tout se déroule comme un job classique.


===== Références =====

  * [[https://apptainer.org/docs/|Documentation officielle Apptainer]]
  * [[https://www.openblas.net/|Site officiel OpenBLAS]]