HyperQueue

HyperQueue (HQ) on tehokas alisolmutason tehtäväajastin. Sen sijaan, että lähettäisit jokaisen laskentatehtäväsi erillisinä Slurm- töinä tai työn vaiheina, voit varata suuren resurssikokonaisuuden ja käyttää sitten HyperQueuea tehtäviesi lähettämiseen tähän varaukseen. Yksi resurssivaraus kuormittaa eräjono järjestelmää huomattavasti vähemmän, ja se on suositeltu tapa suorittaa suuren läpimenon laskennan käyttötapauksia. HyperQueue voi toimia myös tehtävien suorittajana työvuo hallintaohjelmille, kuten Snakemake tai Nextflow.

Saatavilla

Roihu-CPU: 0.25.1
Roihu-GPU: 0.25.1
LUMI: 0.18.0

Lisenssi

Vapaasti käytettävissä ja avointa lähdekoodia MIT-lisenssillä

Käyttö

Moduulin lataaminen

Lataa HyperQueuen oletusversio Roihu-CPU- tai Roihu-GPU-ympäristössä näin:

module load hyperqueue

Jotta voit käyttää CSC:n HyperQueue-moduuleja LUMIssa, sinun täytyy ensin ottaa CSC:n moduulit käyttöön:

module use /appl/local/csc/modulefiles
module load hyperqueue

Tehtävien ajo `sbatch-hq`:lla

Yksinkertaisiin tehtävien rinnakkaisajon työnkulkuihin, joissa haluat ajaa vain monia samankaltaisia, riippumattomia ja ei-MPI-rinnakkaisia ohjelmia, voit käyttää CSC:n aputyökalua sbatch-hq. Se luo ja käynnistää erätyön, joka suorittaa komentosi HyperQueuen avulla ja ajaa niitä, kunnes kaikki ovat valmiita tai erätyön aikaraja saavutetaan.

Määritä ajettavien komentojen lista tiedostossa, yksi komento per rivi. Älä käytä komennoissa srun-komentoa! HyperQueue käynnistää tehtävät varatuilla resursseilla pyydetyllä tavalla. Esimerkiksi tasks-tiedosto voi sisältää:

command1 arguments1
command2 arguments2
# and so on

Lähetä sitten tehtävät ja varaa esimerkiksi kahdeksan ydintä yhdeltä solmulta:

module load sbatch-hq
sbatch-hq --cores=8 --nodes=1 --account=<project> --partition=test --time=00:15:00 tasks

Tiedoston komentojen määrä voi olla (ja yleensä pitäisi olla) paljon suurempi kuin niiden tehtävien määrä, jotka mahtuvat ajettaviksi samanaikaisesti varatuilla solmuilla. Katso lisätietoja käytöstä ja syötevaihtoehdoista komennolla sbatch-hq --help.

HyperQueuen ajaminen Slurm-erätyössä

Jos tarvitset enemmän hallintaa kuin mitä sbatch-hq tarjoaa, voit ohjata HyperQueuea itse Slurm-erätyöstä.

HyperQueue toimii työntekijä-palvelin-asiakas-mallilla. Palvelin hallitsee yhteyksiä työntekijöiden ja asiakkaan välillä. Asiakas lähettää tehtävät palvelimelle, joka välittää ne käytettävissä oleville työntekijöille. Asiakas ja palvelin voivat toimia kirjautumis- tai laskentasolmuilla, ja työntekijät toimivat laskentasolmuilla. HyperQueue muistuttaa Slurmia Slurmin sisällä, mutta sinun täytyy käynnistää palvelin ja työntekijät itse. Suosittelemme lukemaan virallisen HyperQueue-dokumentaation.

Slurm-erätyössä jokainen Slurm-tehtävä vastaa yhtä HyperQueue-työntekijää. Alla oleva esimerkki käyttää työkohtaista hakemistoa, joka sisältää suoritettavan task.sh-skriptin ja batch.sh-skriptin, joka käynnistää palvelimen ja työntekijät, lähettää tehtävät ja sammuttaa kaiken:

.             # Current working directory
├── batch.sh  # Batch script for HyperQueue server and workers
└── task.sh   # Executable task script for HyperQueue

Esimerkki: Yhden solmun työ Roihu-CPU:ssa

task.sh-skripti on suoritettava skripti, joka lähetetään työntekijöille. Oletamme, että tehtävät ovat riippumattomia ja suoritetaan yhdellä solmulla. Tässä on yksinkertainen Bashilla kirjoitettu esimerkki:

task.sh

#!/bin/bash
sleep 1   # ~0.1 ms HyperQueue overhead per task, so even tiny tasks run efficiently

batch.sh-skripti orkestroi ajon. Rivinsisäiset kommentit selittävät jokaisen vaiheen:

batch.sh

#!/bin/bash
#SBATCH --account=<project>
#SBATCH --partition=small
#SBATCH --nodes=1
#SBATCH --ntasks-per-node=1   # one HyperQueue worker
#SBATCH --cpus-per-task=10    # cpus per worker
#SBATCH --mem-per-cpu=1000    # memory per cpu
#SBATCH --time=00:15:00

module load hyperqueue

# Server files go in a job-specific directory: start one server per job to avoid
# mixing up separate computations and the limited storage under $HOME (the default
# location if HQ_SERVER_DIR is unset). All hq commands respect this variable.
export HQ_SERVER_DIR="$PWD/hq-server/$SLURM_JOB_ID"
mkdir -p "$HQ_SERVER_DIR"

# Start the server in the background and wait until it is up. We background it because
# the server keeps running until we stop it and must not block the rest of the script.
hq server start &
until hq job list &> /dev/null ; do sleep 1 ; done

# Start one worker per Slurm task with srun, reserving the requested cpus. We wait for
# all workers to connect so that any worker problems surface early.
srun --overlap --cpu-bind=none --mpi=none hq worker start \
    --manager slurm \
    --on-server-lost finish-running \
    --cpus="$SLURM_CPUS_PER_TASK" &
hq worker wait "$SLURM_NTASKS"

# Submit the tasks (non-blocking). We disable per-task stdout/stderr files to avoid
# excess I/O on the parallel filesystem when there are many tasks. Then wait for them.
hq submit --stdout=none --stderr=none --cpus=1 --array=1-1000 ./task.sh
hq job wait all

# Shut down the workers and server to avoid a false error from Slurm when the job ends.
hq worker stop all
hq server stop

Huomioita resurssipyynnöstä: jokaisesta Slurm-tehtävästä tulee yksi HyperQueue-työntekijä. Käytä valintoja --cpus-per-task ja --mem-per-cpu varataksesi osan solmusta kutakin työntekijää kohden (osittainen solmuvaraus, kuten yllä), tai valintaa --cpus-per-task=<all cpus on a node> yhdessä valinnan --mem=0 kanssa varataksesi kokonaisen solmun työntekijää kohden (täysi solmuvaraus). Kasvata --nodes-arvoa, jos haluat ajaa työntekijöitä useammalla solmulla; alla oleva monisolmuesimerkki käyttää täyttä monisolmuvarausta.

Kannattaa lukea osiot Työt ja tehtävät ja tehtävätaulukot, jotta ymmärrät eri tavat suorittaa laskentaa HyperQueuella. Monimutkaisemmissa tehtäväriippuvuuksissa voit käyttää HyperQueuea muiden työnvuo hallintaohjelmien suorittajana, kuten Snakemake tai Nextflow.

Esimerkki: Monisolmutyö Roihu-CPU:ssa paikallisilla levyillä

Voimme käyttää väliaikaisia paikallisia levyalueita HyperQueuen kanssa I/O-intensiivisten tehtävien suorittamiseen. Koska HyperQueue-tehtävä voi suorittua millä tahansa varatulla solmulla, jokaisen solmun paikallisella levyllä täytyy olla kopio kaikista tiedostoista, joita tehtävä voi käyttää. Tyypillinen työnkulku koostuu seuraavista vaiheista:

Arkistoitujen syötetiedostojen kopiointi ja purkaminen rinnakkaistiedostojärjestelmästä paikalliselle levylle.
Paikallista levyä käyttävien HyperQueue-tehtävien laskenta (hq submit).
Tulostiedostojen arkistointi ja kopiointi paikalliselta levyltä rinnakkais- tiedostojärjestelmään.

Vaiheissa 1 ja 3 voimme suorittaa <executable>-tiedoston jokaisella varatulla solmulla Slurm-työvaiheena seuraavasti:

srun -m arbitrary -w "$SLURM_JOB_NODELIST" <executable>

Ilman näitä valintoja srun suorittaisi ohjelman jokaisessa Slurm-tehtävässä, jotka voisivat olla samalla solmulla. srun-komento voidaan jättää pois, jos pyydetään vain yksi solmu.

Seuraava täydellinen monisolmuesimerkki siirtää syötteen paikalliselle levylle ja tulosteen pois paikalliselta levyltä. Tässä käytetty arkisto input.tar.gz purkautuu input- hakemistoon.

extract.sh

#!/bin/bash
tar xf input.tar.gz -C "$TMPDIR"
mkdir -p "$TMPDIR/output"

task.sh

#!/bin/bash
cd "$TMPDIR"
cat "input/$HQ_TASK_ID.inp" > "output/$HQ_TASK_ID.out"
sleep 1

archive.sh

#!/bin/bash
cd "$TMPDIR"
tar czf "output-$SLURMD_NODENAME.tar.gz" output
cp "output-$SLURMD_NODENAME.tar.gz" "$SLURM_SUBMIT_DIR"

batch.sh

#!/bin/bash
#SBATCH --account=<project>
#SBATCH --partition=medium
#SBATCH --nodes=2
#SBATCH --ntasks-per-node=1
#SBATCH --cpus-per-task=384
#SBATCH --mem=0
#SBATCH --time=00:15:00

module load hyperqueue

# Specify a location and create a directory for the server
export HQ_SERVER_DIR="$PWD/hq-server/$SLURM_JOB_ID"
mkdir -p "$HQ_SERVER_DIR"

# Start the server in the background and wait until it has started
hq server start &
until hq job list &> /dev/null ; do sleep 1 ; done

# Start the workers in the background
srun --overlap --cpu-bind=none --mpi=none hq worker start \
    --manager slurm \
    --on-server-lost finish-running \
    --cpus="$SLURM_CPUS_PER_TASK" &

# Wait until all workers have started
hq worker wait "$SLURM_NTASKS"

# Download some example input files
wget https://a3s.fi/CSC_training/input.tar.gz

# Extract input files to the local disk and create a directory for outputs
srun -m arbitrary -w "$SLURM_JOB_NODELIST" ./extract.sh

# Submit tasks to workers
hq submit --stdout=none --stderr=none --cpus=1 --array=1-1000 ./task.sh

# Wait for all tasks to finish
hq job wait all

# Archive and copy output from each local disk to working directory on Lustre
srun -m arbitrary -w "$SLURM_JOB_NODELIST" ./archive.sh

# Shut down the workers and server
hq worker stop all
hq server stop

Snakemaken tai Nextflown käyttäminen HyperQueuen kanssa

Katso Nextflow- tai Snakemake-sivulta ohjeet HyperQueuen käyttämiseen Nextflow- tai Snakemake-työvuoiden suorittajana.

Monisolmutehtävät

Vaikka HyperQueue ei tue MPI-suoritusta suoraan, se on mahdollista käyttämällä yhdessä HQ-ominaisuutta Monisolmutehtävät sekä orterun-, hydra- tai prrte-työkaluja. Tällä tavoin MPI-tehtäviä voidaan ajastaa solmutason tarkkuudella.

Työntekijöiden automaattinen varaus

Suosittelemme välttämään automaattisen varaajan käyttöä. Se luo automaattisesti eräskriptejä työntekijöiden käynnistämiseen ja lähettää ne, mikä lisää tarpeetonta monimutkaisuutta. Lisäksi automaattisesti luoduissa eräskripteissä on joitakin ongelmia, ja ne voisivat olla joustavampia.

Viitteet

Jos käytät HyperQueuea työssäsi, kehittäjät pyytävät viittaamaan seuraavaan julkaisuun:

Jakub Beránek, Ada Böhm, Gianluca Palermo, Jan Martinovič, Branislav Jansík. HyperQueue: Efficient and ergonomic task graphs on HPC clusters. SoftwareX, 27:101814, 2024. https://doi.org/10.1016/j.softx.2024.101814