====== Tutorial ======

Celem tej instrukcji jest wykonanie pierwszych kroków na klastrze Eden. Po jej przejściu:

  * zalogujesz się na Eden,
  * sprawdzisz dostępne zasoby,
  * uruchomisz pierwsze zadanie,
  * sprawdzisz jego stan,
  * zakończysz zadanie.

===== Logowanie =====

Logowanie do systemu Eden jest możliwe przez SSH.

==== Z sieci wydziałowej ====

Będąc w sieci wydziałowej, możesz połączyć się bezpośrednio:

<code bash>
ssh LOGIN_EDEN@eden.mini.pw.edu.pl
</code>

Zastąp ''LOGIN_EDEN'' swoim loginem na klastrze Eden.

==== Spoza sieci wydziałowej ====

Spoza sieci wydziałowej możesz połączyć się pośrednio, wykorzystując serwer wydziałowy jako tzw. //jump host//.

Służy do tego flaga ''-J'':

<code bash>
ssh -J LOGIN_MINI@ssh.mini.pw.edu.pl LOGIN_EDEN@eden.mini.pw.edu.pl
</code>

W tym przypadku najpierw następuje autoryzacja na serwerze wydziałowym, a następnie ruch jest automatycznie przekierowywany na klaster Eden.

Zastąp:

  * ''LOGIN_MINI'' swoim loginem wydziałowym,
  * ''LOGIN_EDEN'' swoim loginem na klastrze Eden.

Po poprawnym zalogowaniu powinieneś zobaczyć ekran powitalny Eden:

{{:pl:first_steps:tutorial_1.png?900|Ekran powitalny po zalogowaniu do Eden}}

<WRAP center round important 80%>
**Eden, na który logujesz się przez SSH, jest tylko węzłem dostępowym. Nie wykonujemy na nim obliczeń!**
</WRAP>

Po zalogowaniu mamy dostęp do terminala z systemem Linux oraz do systemu kolejkowego Slurm, za pomocą którego uruchamiamy zadania na klastrze.

===== Podstawowe komendy =====

Przydatne polecenia:

  * ''sfree'' — wyświetla aktualnie wolne zasoby na klastrze.
  * ''pestat'' — pokazuje status węzłów i informacje o tym, kto aktualnie używa zasobów.
  * ''squeue'' — wyświetla całą kolejkę zadań.
  * ''squeue -u LOGIN_EDEN'' — pokazuje tylko Twoje zadania.
  * ''sinfo'' — wyświetla informacje o dostępnych partycjach (kolejkach) i stanie węzłów.
  * ''sshare -l'' — wyświetla informacje o udziałach (FairShare) i priorytetach użytkowników.

==== Zatrzymanie zadania ====

Jeżeli chcesz przerwać swoje zadanie, najpierw sprawdź jego identyfikator ''JOBID'':

<code bash>
squeue -u LOGIN_EDEN
</code>

Następnie użyj:

<code bash>
scancel JOBID
</code>

===== Uruchamianie zadań interaktywnych =====

Sesja interaktywna jest wygodna do krótkich testów, eksperymentowania oraz sprawdzania kodu na węźle obliczeniowym.

Najpierw zobaczmy, jakie kolejki są dostępne:

<code bash>
sinfo
</code>

Przykładowy wynik:

{{:pl:first_steps:tutorial_2.png?900|Przykładowy wynik polecenia sinfo}}

Widzimy m.in. kolejkę ''student''.

Możemy też sprawdzić, jakie zasoby są obecnie wolne:

<code bash>
sfree
</code>

Przykładowy wynik:

{{:pl:first_steps:tutorial_3.png?900|Przykładowy wynik polecenia sfree}}

O, widzimy że zarówno węzeł ''stud-1'', jak i ''stud-2'' mają wolne CPU. Uruchommy sesję z:

  * 1 CPU,
  * 4 GB RAM,
  * maksymalnym czasem pracy 30 minut.

Uruchamiamy:

<code bash>
srun -p student -A GROUP_NAME --cpus-per-task=1 --mem=4G --time=00:30:00 --pty bash
</code>

Zastąp ''GROUP_NAME'' nazwą swojej grupy.

Gdy system przyzna nam zasoby, możemy sprawdzić, na jakim węźle się znajdujemy:

<code bash>
hostname
</code>

Przykładowe uruchomienie sesji:

{{:pl:first_steps:tutorial_4.png?1000|Uruchomienie sesji interaktywnej i sprawdzenie nazwy węzła}}

Widzimy, że dostaliśmy ''stud-1''. Zmienił się również prompt terminala z ''@eden'' na ''@stud-1''. Oznacza to, że jesteśmy już na węźle obliczeniowym.

Możemy tutaj uruchamiać obliczenia, testować kod, uruchomić Pythona itd.

Po zakończeniu pracy wychodzimy z sesji:

<code bash>
exit
</code>

<WRAP center round important 80%>
**Jeżeli przerwie się połączenie SSH, obliczenia uruchomione w sesji interaktywnej również zostaną przerwane.**

Można temu zapobiec, korzystając np. z ''tmux'' albo ''screen''.
</WRAP>

==== Co oznaczają poszczególne opcje? ====

  * ''srun'' — narzędzie służące do uruchamiania zadań. W tej konfiguracji pozwala na pracę interaktywną.
  * ''-p student'' — wybiera partycję (kolejkę) o nazwie ''student''.
  * ''-A GROUP_NAME'' — przypisuje zadanie do konkretnej grupy rozliczeniowej lub projektu.
  * ''--cpus-per-task=1'' — żąda jednego rdzenia CPU.
  * ''--gres=gpu:NUM_OF_GPUS'' — żąda dostępu do określonej liczby GPU, np. ''--gres=gpu:1''.
  * ''--mem=MEM_IN_MBYTES'' — rezerwuje pamięć RAM dla całego zadania, np. ''--mem=4000M'' lub ''--mem=4G''.
  * ''--time=TIME'' — ustala maksymalny czas trwania zadania w formacie ''DD-HH:MM:SS'', np. ''--time=00:30:00''. Po upływie tego czasu zadanie zostanie zakończone.
  * ''--pty bash'' — tworzy interaktywny pseudoterminal z powłoką Bash.

===== Zadania wykonywane w tle =====

Do dłuższych obliczeń nie należy używać sesji interaktywnej. Lepszym rozwiązaniem są zadania wysyłane za pomocą ''sbatch''.

Opis zadania oraz wymagane zasoby zapisujemy w pliku tekstowym.

Plik składa się z:

  * dyrektyw Slurma — linii zaczynających się od ''#SBATCH'',
  * poleceń, które mają zostać wykonane.

Pierwsza linia powinna wskazywać interpreter, np.:

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

==== Przykład krok po kroku ====

=== 1. Przygotowanie programu ===

Utwórzmy prosty program w Pythonie:

<code bash>
echo 'print("Hello Eden")' > hello.py
</code>

=== 2. Przygotowanie skryptu Slurm ===

Tworzymy plik ''hello.sh'' o następującej zawartości:

<code bash>
#!/usr/bin/env bash
#SBATCH --partition student
#SBATCH --account=GROUP_NAME
#SBATCH --cpus-per-task=1
#SBATCH --gres=gpu:0
#SBATCH --mem=4G
#SBATCH --time=00:10:00
#SBATCH --job-name=hello_test
#SBATCH --output=slurm_logs/hello_test-%j.log

python3 hello.py
</code>

Zastąp ''GROUP_NAME'' nazwą swojej grupy.

Symbol ''%j'' w nazwie pliku zostanie automatycznie zastąpiony numerem ''JOBID'' danego zadania.

=== 3. Utworzenie katalogu na logi ===

Przed wysłaniem zadania upewnij się, że katalog na logi istnieje.

Slurm nie utworzy go automatycznie.

<code bash>
mkdir -p slurm_logs
</code>

=== 4. Wysłanie zadania ===

Wysyłamy zadanie do kolejki:

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

Slurm zwróci komunikat podobny do:

<code>
Submitted batch job 1752516
</code>

Przykład:

{{:pl:first_steps:tutorial_5.png?700|Wysłanie zadania za pomocą sbatch}}

Liczba na końcu to ''JOBID'' zadania.

Możemy sprawdzić, czy zadanie znajduje się w kolejce:

<code bash>
squeue -u LOGIN_EDEN
</code>

=== 5. Sprawdzenie wyniku ===

Po zakończeniu zadania wynik znajdziemy w katalogu ''slurm_logs''.

Przykładowo, jeżeli ''JOBID'' zadania wynosi ''12345'':

<code bash>
cat slurm_logs/hello_test-12345.log
</code>

Powinniśmy zobaczyć:

<code>
Hello Eden
</code>

Przykład dla zadania o ''JOBID'' równym ''1752516'':

{{:pl:first_steps:tutorial_6.png?1000|Odczytanie wyniku zadania z pliku logu}}

==== Zadanie, które możemy zobaczyć w kolejce ====

Poprzedni program wykonuje się tak szybko, że możemy nie zdążyć zobaczyć go za pomocą ''squeue''.

Zmieńmy więc ''hello.py'' na:

<code python>
import time

print("Hello Eden")
time.sleep(30)
print("Hello Eden after sleep")
</code>

Ponownie uruchamiamy:

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

i od razu sprawdzamy kolejkę:

<code bash>
squeue -u LOGIN_EDEN
</code>

Przykładowy wynik:

{{:pl:first_steps:tutorial_8.png?1000|Zadanie widoczne w kolejce Slurm}}

Jeżeli zadanie zostało już uruchomione, przez około 30 sekund powinniśmy zobaczyć je na liście.

W kolumnie ''ST'' wartość ''R'' oznacza, że zadanie jest aktualnie wykonywane (//Running//).

Po jego zakończeniu ponowne wykonanie:

<code bash>
squeue -u LOGIN_EDEN
</code>

nie powinno już go pokazywać.

===== Czym jest Slurm? =====

Slurm jest systemem zarządzania klastrami i planowania zadań powszechnie wykorzystywanym w środowiskach HPC i na superkomputerach.

Jego głównym zadaniem jest:

  * przydzielanie użytkownikom zasobów obliczeniowych,
  * zarządzanie kolejką zadań,
  * uruchamianie zadań na dostępnych węzłach,
  * zwalnianie zasobów po zakończeniu obliczeń.

Typowy przebieg pracy wygląda następująco:

  - Użytkownik przygotowuje skrypt ''sbatch'', w którym określa potrzebne zasoby i polecenia do wykonania, a następnie wysyła zadanie do kolejki.
  - Slurm sprawdza dostępność zasobów.
  - Gdy odpowiednie zasoby są dostępne, Slurm je rezerwuje i uruchamia zadanie.
  - Po zakończeniu obliczeń zasoby zostają zwolnione i mogą zostać przydzielone kolejnemu zadaniu.

Oficjalna dokumentacja:

[[https://slurm.schedmd.com/documentation.html|Dokumentacja Slurm]]

===== Dalsze kroki =====

TODO

----

//Tutorial przygotowany na podstawie materiałów opracowanych przez **Tymona Tumialisa**. Dziękujemy za przygotowanie instrukcji, przykładów oraz materiałów graficznych.//