Mostra la font per a Manual Cluster HPC UVic-UCC

=== Introducció i Recursos del Clúster ===
Aquest manual està dissenyat per ajudar els nous usuaris del clúster de càlcul de la UVic-UCC. El seu objectiu és proporcionar les eines necessàries per començar a utilitzar el clúster de manera eficient. Es recomana tenir coneixements bàsics del sistema Unix per poder treballar còmodament.

==== Què és un clúster de càlcul? ====
Un clúster de càlcul és un conjunt d'ordinadors que treballen conjuntament per processar tasques de manera eficient. Un dels ordinadors, anomenat node mestre o node d'inici de sessió, s'encarrega d'assignar els programes (anomenats jobs) als altres ordinadors mitjançant un gestor de cues (scheduler).
[[Fitxer:Compute cluster.png|center|miniatura|600x600px|Representació esquemàtica d'un clúster de càlcul.]]

==== Recursos del Clúster ====

* 112 CPUs: Distribuïdes en diferents nodes per optimitzar el càlcul paral·lel.
* 515 GB de RAM: Repartida segons les necessitats dels usuaris.
* 2 GPUs: Disponibles per a càlculs d'intel·ligència artificial.
* 8 TB d'emmagatzematge: Per guardar dades i resultats.

==== Sistema de Gestió de Jobs: Slurm ====
Un cop dins del clúster, utilitzem el sistema Slurm Management. Podeu trobar la documentació oficial en aquest enllaç: [https://slurm.schedmd.com/documentation.html Documentació de Slurm]. Per a més informació sobre el nostre cluster de càlcul, veieu la presentació [https://recursosdocents.uvic.cat/images/7/70/Presentacio.pdf Presentació clúster de càlcul UVic-UCC] (Last update 15/01/2025).

==== Administradors del clúster ====

* Jordi Sala Serra: Tècnic de l'àrea TIC de la UVic-UCC (jordi.sala@uvic.cat).
* Roger Casals Franch: Responsable d'usuaris i programari de recerca, INVESTIGO a l'IRIS-CC i doctorand al SGR BI² (roger.casals@uvic.cat).

=== Connectar-se via VPN i SSH ===

==== Connexió VPN ====
Primer de tot, per tal de connectar-vos al cluster, heu d'obrir el túnel via VPN. Us heu de descarregar la versió de [https://www.fortinet.com/support/product-downloads Forticlient] que sigui compatible amb el vostre sistema operatiu. Seguidament un cop us hagueu descarregat FortiClient, heu d'anar a l'apartat "Remote Access" i configurar de la següent manera.

* Teams Haureu estat acceptat dins d'un grup d'Users, a l'apartat Bloc de notes de l'HPC trobareu com connectar-vos via VPN.

==== Connexió SSH ====
Un cop hagueu activat la connexió via VPN. Per connectar-vos al clúster, executeu la següent comanda al terminal:

<code>ssh -l nom.cognom@uvic.cat lavandula.uvic.local</code>

Introduïu la contrasenya del vostre Campus Virtual quan us la demani. Tingueu en compte que no podeu treballar de manera interactiva al clúster; és obligatori enviar jobs mitjançant Slurm.

=== Guia Bàsica per Enviar Jobs ===

==== Crear un Fitxer de Treball (Script sbatch) ====
Es recomana mantenir una estructura clara per als vostres directoris:

Per a tal de crear directoris al vostre "home", heu d'utilitzar

<code>mkdir</code>

* data/: Conté les dades d'entrada.
* results/: Guarda els resultats del càlcul.
* scripts/: Inclou els scripts de treball (.sh).

Heu de crear un fitxer de 0, que contingui les comandes #SBATCH i canviar-les segons els requeriments.

'''Exemple de Script Bàsic:'''

<code>#!/bin/bash</code>

<code>#SBATCH --job-name=nom_job          # Nom del job</code>

<code>#SBATCH --output=sortida.txt        # Fitxer de sortida</code>

<code>#SBATCH --error=error.txt           # Fitxer d’errors</code>

<code>#SBATCH --time=01:00:00             # Temps màxim (hh:mm:ss)</code>

<code>#SBATCH --cpus-per-task=4           # Nombre de CPUs per tasca</code>

<code>#SBATCH --mem=4GB                   # Memòria assignada</code>

<code>python script.py                    # Execució del vostre codi</code>

<code>Rscript script.R                    # En cas que fos R</code>	 

'''Comentaris:'''

<code>--job-name</code>: Assigna un nom al vostre job per identificar-lo fàcilment.

<code>--output</code>: Especifica el fitxer on es guardarà la sortida del job.

<code>--error</code>: Indica el fitxer on es guardaran els errors.

<code>--time</code>: Defineix el temps màxim d'execució del job.

<code>--cpus-per-task</code>: Estableix el nombre de CPUs assignades al job.

<code>--mem</code>: Defineix la memòria necessària per al job.

'''Comandaments de Slurm'''

==== Enviar el Job a Slurm ====
Per enviar el job, utilitzeu:

<code>sbatch job_script.sh</code>

Això us retornarà un '''Job ID''' (per exemple, <code>12345</code>) que us servirà per fer seguiment del job.

==== Consultar l’Estat dels Vostres Jobs ====
Per veure l’estat dels vostres jobs (si estan en cua o en execució), utilitzeu:

<code>squeue</code>

Estats Comuns:

* '''PD (PENDING)''': El job està en cua.
* '''R (RUNNING)''': El job està en execució.

==== Cancel·lar un Job ====
Si necessiteu cancel·lar un job, utilitzeu:

<code>scancel 12345</code>

==== Comprovar els Recursos Disponibles ====
Per veure quins recursos (nodes i particions) estan disponibles, utilitzeu:

<code>sinfo</code>

=== Comandes bàsiques de SLURM ===

==== Consultar l’estat del clúster ====

* <code>sinfo</code> → Mostra l’estat dels nodes i particions disponibles.
* <code>squeue</code> → Mostra tots els treballs en cua.
* <code>squeue -u $USER</code> → Mostra només els teus treballs en cua.
* <code>squeue -j</code> → Consulta l'estat d'un treball específic.

==== Enviament de treballs ====

* <code>sbatch script.sh</code> → Envia un treball al clúster mitjançant un script.

==== Gestió de treballs ====

* <code>scancel</code> → Cancel·la un treball específic.
* <code>scancel -u $USER</code> → Cancel·la tots els teus treballs en execució.
* <code>scontrol show job</code> → Mostra informació detallada d’un treball.
* <code>seff job</code> → Mostra l'informe d'eficiència que s'envia per correu.

==== Transferència de fitxers ====
Per enviar i rebre fitxers entre el vostre ordinador i el clúster, utilitzeu la comanda <code>scp</code>. Si voleu copiar tot un directori, podeu utilitzar <code>scp -r</code>. IMPORTANT: La transferència s’ha de fer sempre des del vostre ordinador.

'''Exemples:'''

* Copiar un fitxer des del vostre ordinador al clúster:
** <code>scp fitxer.txt NIU@uvic.local@lavandula:CARPETA/CARPETA</code>

* Copiar un fitxer del clúster al vostre ordinador:
** <code>scp NIU@uvic.local@lavandula:CARPETA/CARPETA/fitxer.txt .</code>

(El punt final indica que es copiarà al directori actual.)

=== Informació de Particions ===
{| class="wikitable"
!Nom de la Partició
!Node
!CPUs
!Memòria (MB)
!GPU
|-
|highmem
|vcompute11
|42
|224452
|0
|-
|normal1
|vcompute12
|14
|30052
|0
|-
|normal2
|vcompute13
|14
|30052
|0
|-
|normal3
|vcompute14
|14
|30052
|0
|-
|normal4
|vcompute15
|14
|30052
|0
|-
|normal5
|vcompute16
|14
|30052
|0
|-
|gpu
|compute02
|40
|32008
|2
|-
|lowmem
|compute02
|40
|32008
|0
|}

=== Apptainer ===
Apptainer és una eina de contenidors dissenyada per facilitar l'execució d'aplicacions amb totes les seves dependències en entorns HPC. Com que ja està instal·lat en el nostre sistema, aquest tutorial se centrarà en com construir i utilitzar imatges de contenidors.

==== Creació d'una imatge amb un fitxer de recepta ====
El primer pas és crear un fitxer de recepta (definition file).def que descrigui la base i les instruccions per construir la imatge. Per exemple, crea un fitxer anomenat <code>apptainer.def</code> amb el següent contingut:

<code>Bootstrap: docker</code>

<code>From: ubuntu:20.04</code>

<code>%post</code>

<code>    apt-get update && apt-get install -y python3     # Aquí pots instal·lar tots els paquets / llibreries necessàries</code>

<code>%runscript</code>

<code>    exec python3 "$@"</code>

Aquest fitxer indica que la imatge es basarà en Ubuntu 20.04 i instal·larà Python3, segons les necessitats de l'usuari

==== Construir la imatge ====
Una imatge és un fitxer que encapsula tot l'entorn necessari (sistema operatiu, aplicacions i dependències) per executar una aplicació de manera consistent i portable. Per construir la imatge, obre la terminal i executa:

<code>apptainer build my_image.sif apptainer.d</code>ef

Aquesta comanda crea un fitxer <code>my_image.sif</code> que conté la imatge del teu contenidor.

'''Convertir des de docker'''

Per tal de poder descarregar directament una imatge de de docker, fem servir aquest codi, que generarà un fitxer .sif que ja el podrem executar.

<code>apptainer pull docker://contenidor-d'interès</code>

==== Executar la imatge ====
Un cop creada la imatge, pots executar-la creant un altre fitxer sbatch, i per defecte ja podràs usar apptainer.

<code>#!/bin/bash</code>

<code>#SBATCH --job-name=apptainer_test    # Nom del job</code>

<code>#SBATCH --output=output.log          # Fitxer on es guarda la sortida</code>

<code>#SBATCH --error=error.log            # Fitxer per errors</code>

<code>#SBATCH --time=00:10:00              # Temps màxim d'execució</code>

<code>#SBATCH --mem=1G                     # Memòria total requerida</code>

<code>#SBATCH --cpus-per-task=1            # Nombre de CPUs</code>

<code>#SBATCH --partition=normal1          # Partició a utilitzar</code>

<code># Executar la comanda dins del contenidor Apptainer</code>

<code>apptainer run my_image.sif   # Run fa córrer tot el contenidor, si fessis servir exec, només executa la comanda que es vulgui.</code>

    

Això obrirà una shell dins el contenidor o executarà l'aplicació definida al bloc %runscript del fitxer de recepta.

'''Recursos addicionals'''

Per a més tutorials i informació detallada sobre com treballar amb imatges en Apptainer, consulta la [https://apptainer.org/docs/user/main/quick_start.html# documentació oficial d'Apptainer].

=== Easybuild ===
Easybuild és una eina automatitzada dissenyada per compilar i instal·lar programari en entorns HPC. Facilita la gestió de les dependències i versions, fent que la instal·lació d'aplicacions complexes sigui molt més senzilla i menys propensa a errors.

Aquesta eina és especialment útil per a usuaris novells, ja que redueix la complexitat de configurar el software manualment. Pròximament, també introduirem un tutorial detallat per mostrar-te com utilitzar Easybuild en el teu entorn de treball.

=== Com obrir tiquets ===
Per tal d'obrir tiquets a l'URespon, ja sigui per a instal·lació de software, altes de usuaris, o problemes de connexió, seguir el següent tutorial. Per a més informació, seguiu el següent [https://recursosdocents.uvic.cat/images/b/b8/URespon_cluster.pdf Tutorial per obrir incidències o sol·licituds per al clúster de càlcul]

=== Com interpretar i millorar l'eficiència ===
Per garantir un bon funcionament del clúster per a tothom, és important que cada usuari optimitzi els recursos que sol·licita. En el tutorial [https://recursosdocents.uvic.cat/images/5/5f/Use_resources_efficient.pdf Com optimitzar els recursos], informe d'eficiència t’expliquem com pots fer-ho de manera senzilla.


---

Manual creat per ajudar a nous usuaris del clúster UVic-UCC.