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).

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ç: Documentació de Slurm. Per a més informació sobre el nostre cluster de càlcul, veieu la presentació.

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

1. 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 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-lo de la manera següent.

• 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.

2. Connexió SSH

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

ssh -l nom.cognom@uvic.cat lavandula.uvic.local

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

1. Crear un Fitxer de Treball (Script sbatch)

Es recomana mantenir una estructura clara per als vostres directoris:

• Per crear directoris al vostre home, heu d'utilitzar mkdir.
• 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 text que contingui les comandes #SBATCH i adaptar-les segons els requeriments del vostre càlcul.

Exemple de Script Bàsic:

#!/bin/bash
#SBATCH --job-name=nom_job          # Nom del job
#SBATCH --output=sortida.txt        # Fitxer de sortida
#SBATCH --error=error.txt           # Fitxer d’errors
#SBATCH --time=01:00:00             # Temps màxim (hh:mm:ss)
#SBATCH --cpus-per-task=4           # Nombre de CPUs per tasca
#SBATCH --mem=4GB                   # Memòria assignada

python script.py                    # Execució del vostre codi
Rscript script.R                    # En cas que fos R

Comentaris:

• --job-name: Assigna un nom al vostre job per identificar-lo fàcilment.
• --output: Especifica el fitxer on es guardarà la sortida del job.
• --error: Indica el fitxer on es guardaran els errors.
• --time: Defineix el temps màxim d'execució del job.
• --cpus-per-task: Estableix el nombre de CPUs assignades al job.
• --mem: Defineix la memòria necessària per al job.

Comandaments de Slurm

2. Enviar el Job a Slurm

Per enviar el job, utilitzeu:

sbatch job_script.sh

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

3. Consultar l’Estat dels Vostres Jobs

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

squeue

Estats Comuns:

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

4. Cancel·lar un Job

Si necessiteu cancel·lar un job, utilitzeu:

scancel 12345

5. Comprovar els Recursos Disponibles

Per veure quins recursos (nodes i particions) estan disponibles, utilitzeu:

sinfo

Comandes bàsiques de SLURM

1. Consultar l’estat del clúster

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

2. Enviament de treballs

• sbatch script.sh → Envia un treball al clúster mitjançant un script.

3. Gestió de treballs

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

4. Transferència de fitxers

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

Exemples:

• Copiar un fitxer des del vostre ordinador al clúster:

  scp fitxer.txt NIU@uvic.local@lavandula:CARPETA/CARPETA

• Copiar un fitxer del clúster al vostre ordinador:

  scp NIU@uvic.local@lavandula:CARPETA/CARPETA/fitxer.txt .

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

Informació de Particions

Exemples de Scripts

Aquí teniu alguns scripts Slurm de referència per a càlculs de química computacional sobre CPU. Podeu descarregar-los o adaptar-los a les vostres dades i al software instal·lat al clúster.

• OpenMM en paral·lel sobre CPU
• AMBER en paral·lel sobre CPU
• EVB sobre CPU

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 centra en com construir i utilitzar imatges de contenidors.

1. 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 apptainer.def amb el següent contingut:

Bootstrap: docker
From: ubuntu:20.04

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

%runscript
    exec python3 "$@"

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

2. 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:

apptainer build my_image.sif apptainer.def

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

Convertir des de docker

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

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

3. Executar la imatge

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

#!/bin/bash
#SBATCH --job-name=apptainer_test    # Nom del job
#SBATCH --output=output.log          # Fitxer on es guarda la sortida
#SBATCH --error=error.log            # Fitxer per errors
#SBATCH --time=00:10:00              # Temps màxim d'execució
#SBATCH --mem=1G                     # Memòria total requerida
#SBATCH --cpus-per-task=1            # Nombre de CPUs
#SBATCH --partition=normal1          # Partició a utilitzar

# Executar la comanda dins del contenidor Apptainer
apptainer run my_image.sif   # Run fa córrer tot el contenidor, si fessis servir exec, només executa la comanda que es vulgui.

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 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ó, seguiu el següent tutorial. Per a més informació, consulteu el document següent.

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 aquest tutorial t’expliquem com pots fer-ho de manera senzilla.

Introduction and Cluster Resources

This guide is designed to help new users of the UVic-UCC computing cluster. Its goal is to provide the tools needed to start using the cluster efficiently. Basic knowledge of Unix systems is recommended so you can work comfortably.

What is a computing cluster?

A computing cluster is a group of computers that work together to process tasks efficiently. One of the computers, called the master node or login node, is responsible for assigning programs (called jobs) to the other computers through a queue manager (scheduler).

Cluster Resources

• 112 CPUs: Distributed across different nodes to optimize parallel computing.
• 515 GB RAM: Allocated according to user needs.
• 2 GPUs: Available for artificial intelligence workloads.
• 8 TB storage: To store data and results.

Job Management System: Slurm

Once you are inside the cluster, we use the Slurm Management system. You can find the official documentation here: Slurm documentation. For more information about our computing cluster, see the presentation below.

Cluster administrators

• Jordi Sala Serra: Technician in the UVic-UCC ICT area (jordi.sala@uvic.cat).
• Roger Casals Franch: Research software and user support lead, INVESTIGO at IRIS-CC and PhD candidate at SGR BI² (roger.casals@uvic.cat).

Connect via VPN and SSH

1. VPN connection

First of all, to connect to the cluster you must open the VPN tunnel. Download the version of FortiClient that is compatible with your operating system. Once you have installed FortiClient, go to the "Remote Access" section and configure it as follows.

• Teams: You must have been accepted into a users group. In the HPC Notes section you will find how to connect through the VPN.

2. SSH connection

After you activate the VPN connection, run the following command in the terminal to connect to the cluster:

ssh -l name.surname@uvic.cat lavandula.uvic.local

Enter your Campus Virtual password when prompted. Please note that you cannot work interactively on the cluster; jobs must be submitted through Slurm.

Basic Guide to Submitting Jobs

1. Create a job file (sbatch script)

It is recommended to keep a clear directory structure:

• To create directories in your home, use mkdir.
• data/: Contains the input data.
• results/: Stores the calculation results.
• scripts/: Includes the job scripts (.sh).

Create a new file containing the #SBATCH directives and adapt them to your requirements.

Basic script example:

#!/bin/bash
#SBATCH --job-name=job_name         # Job name
#SBATCH --output=output.txt         # Output file
#SBATCH --error=error.txt           # Error file
#SBATCH --time=01:00:00             # Maximum time (hh:mm:ss)
#SBATCH --cpus-per-task=4           # Number of CPUs per task
#SBATCH --mem=4GB                   # Assigned memory

python script.py                    # Run your code
Rscript script.R                    # If you are running R

Comments:

• --job-name: Assigns a name to your job so it is easy to identify.
• --output: Specifies the file where the job output will be stored.
• --error: Indicates the file where errors will be stored.
• --time: Defines the maximum execution time for the job.
• --cpus-per-task: Sets the number of CPUs assigned to the job.
• --mem: Defines the memory required for the job.

Slurm commands

2. Submit the job to Slurm

To submit the job, use:

sbatch job_script.sh

This will return a Job ID (for example, 12345) that you can use to track the job.

3. Check the status of your jobs

To see the status of your jobs (whether they are queued or running), use:

squeue

Common states:

• PD (PENDING): The job is waiting in the queue.
• R (RUNNING): The job is currently running.

4. Cancel a job

If you need to cancel a job, use:

scancel 12345

5. Check available resources

To see which resources (nodes and partitions) are available, use:

sinfo

Basic SLURM commands

1. Check cluster status

• sinfo → Shows the status of available nodes and partitions.
• squeue → Shows all queued jobs.
• squeue -u $USER → Shows only your queued jobs.
• squeue -j <job_id> → Checks the status of a specific job.

2. Submit jobs

• sbatch script.sh → Submits a job to the cluster using a script.

3. Manage jobs

• scancel <job_id> → Cancels a specific job.
• scancel -u $USER → Cancels all your running jobs.
• scontrol show job <job_id> → Shows detailed information about a job.
• seff job <job_id> → Shows the efficiency report that is sent by email.

4. File transfer

To send and receive files between your computer and the cluster, use the scp command. If you want to copy an entire directory, you can use scp -r. IMPORTANT: Transfers must always be started from your own computer.

Examples:

• Copy a file from your computer to the cluster:

  scp file.txt NIU@uvic.local@lavandula:FOLDER/FOLDER

• Copy a file from the cluster to your computer:

  scp NIU@uvic.local@lavandula:FOLDER/FOLDER/file.txt .

  (The final dot means it will be copied to the current directory.)

Partition Information

Script Examples

You can download a few reference Slurm scripts to run computational chemistry CPU jobs or adapt them to your own input data and to the software available on the cluster.

• OpenMM parallel CPU example
• AMBER parallel CPU example
• EVB CPU example

Apptainer

Apptainer is a container tool designed to make it easier to run applications with all their dependencies in HPC environments. Since it is already installed on our system, this tutorial focuses on how to build and use container images.

1. Create an image with a recipe file

The first step is to create a recipe file (definition file) .def that describes the base image and the instructions used to build it. For example, create a file called apptainer.def with the following content:

Bootstrap: docker
From: ubuntu:20.04

%post
    apt-get update && apt-get install -y python3     # Install any packages / libraries you need here

%runscript
    exec python3 "$@"

This file indicates that the image will be based on Ubuntu 20.04 and will install Python3, depending on the user's needs.

2. Build the image

An image is a file that packages the full environment needed to run an application consistently and portably, including the operating system, applications, and dependencies. To build the image, open a terminal and run:

apptainer build my_image.sif apptainer.def

This command creates a file called my_image.sif that contains your container image.

Convert from Docker

To download an image directly from Docker, use the following command, which will generate a .sif file that you can run immediately.

apptainer pull docker://container-of-interest

3. Run the image

Once the image has been created, you can run it by creating another sbatch file. Apptainer will then be available by default.

#!/bin/bash
#SBATCH --job-name=apptainer_test    # Job name
#SBATCH --output=output.log          # File where the output is stored
#SBATCH --error=error.log            # Error file
#SBATCH --time=00:10:00              # Maximum execution time
#SBATCH --mem=1G                     # Total required memory
#SBATCH --cpus-per-task=1            # Number of CPUs
#SBATCH --partition=normal1          # Partition to use

# Run the command inside the Apptainer container
apptainer run my_image.sif   # run executes the full container; exec would only run the specific command you provide.

This will open a shell inside the container or execute the application defined in the %runscript block of the recipe file.

Additional resources

For more tutorials and detailed information about working with Apptainer images, see the official Apptainer documentation.

Easybuild

Easybuild is an automated tool designed to compile and install software in HPC environments. It simplifies dependency and version management, making the installation of complex applications much easier and less error-prone.

This tool is especially useful for new users because it reduces the complexity of configuring software manually. A more detailed tutorial on how to use Easybuild in your working environment will be added soon.

How to open tickets

To open tickets in URespon, whether for software installation, new user registrations, or connection problems, follow the tutorial below. For more information, see the following document.

How to understand and improve efficiency

To ensure the cluster works well for everyone, it is important that each user optimizes the resources they request. In this tutorial, we explain how to do this in a simple way.