# Slurm簡介
++本章節所有指令皆需進入”登入節點”執行，請參考[登入節點](https://man.twcc.ai/@f1-manual/login_node)的連線操作方式。++
[TOC]
## 查詢計畫錢包資訊
:::success
提交計算工作前，請先確認計畫代號(PROJECT_ID)與iService 計畫錢包(SU_BALANCE)的餘額，<font color="#f00">必須加入有效計畫且錢包餘額為正數才能成功派送您的計算工作</font>，請使用 ==wallet== 指令確認計畫代號(PROJECT_ID)與iService 計畫錢包(SU_BALANCE) 餘額：
```
[user@ilgn01]$ wallet
INFO: If you belong to many projects, it may take up to 5 seconds or more.
INFO: Specifying a project should be faster. `wallet $PROJECT_ID`
PROJECT_ID: GOVXXXXXX, PROJECT_NAME: XXX計畫, SU_BALANCE: 2024
```
:::
## Slurm基本概念
:::success
創進一號使用SLURM（Simple Linux Utility for Resource Management）工作排程軟體，以下說明Slurm常用的名詞基本概念：
1. 計畫代號 (Account)：Slurm Account在創進一號代表iService計畫代號，提交工作前必須加入iService有效計畫及錢包餘額為正數。 [查詢計畫代號教學](https://man.twcc.ai/@f1-manual/iService#%E8%A8%88%E7%95%AB%E7%B3%BB%E7%B5%B1%E4%BB%A3%E8%99%9F%E6%9F%A5%E8%A9%A2)
Slurm指令可使用參數 ==-A, --account =<account>== 指定計畫代號(PROJECT_ID)。
```
#SBATCH --account = CHC199166
或是
#SBATCH -A CHC199166
```
2. 節點（Node）：Slurm 大致可區分為三個節點角色：
(1) 管理節點 (Head Node)：管理Slurm叢集系統、工作與排程等。
(2) 工作派送節點 (Submit Node)：供用戶登入提交與管理計算工作的節點，如登入節點。
(3) 計算節點 (Worker Node)：工作派送後，實際執行程式運算的節點，如指令`sinfo`的NODELIST欄位就是計算節點清單。
3. 佇列（Partition）： 將多個計算節點組成一個集合，若計算節點的硬體配置不同，透過佇列（Partition）可以幫助使用者選擇合適的節點並派送工作進行運算，例如CPU專用佇列與GPU專用佇列。 [查詢佇列(partition)教學](https://man.twcc.ai/@f1-manual/slurm_instructions#Slurm%E4%BD%87%E5%88%97-Partition)
Slurm指令可使用參數 ==-p, --partition=<partition>== 指定佇列(Partition)。
```
#SBATCH --partition = development
或是
#SBATCH -p development
```
4. 工作（Job）：工作是在一個或多個計算節點上執行相同的程式。用戶可以通過提交一個工作給SLURM管理節點，然後SLURM管理節點會分配資源給該工作，並在適當的計算節點上執行。
5. 工作識別碼 (Job ID)：在Slurm中提交的工作都會被分配一個唯一的識別碼，稱為"job ID"。
++這個ID是由SLURM系統自動產生的，用戶可以使用這個ID來檢查工作的狀態、終止工作或查詢工作的詳細資訊。++
Slurm指令可使用參數 ==-j, --jobs=<job_id>== 指定工作(Job)。
6. 工作名稱 (Job Name)：是用戶指定的一個用於識別工作的名稱。工作名稱可以是任何用戶選擇的字串，通常用於方便用戶識別和管理提交的工作。
Slurm指令可使用參數 ==-J, --job-name=<job_name>== 指定工作名稱(Job Name)。
job-name是用string來儲存字元。
<font color="red">備註:
命名時請盡量不要使用特殊字元 # ' " : # ' : ! . ^ & ? *< > / @ ~ | 等，
\ (反斜線)不會印出來，不接受空格。 </font>
容許的字元為 A-Z、a-z、0-9、_(底線)、-(連字號)
字串長度限制為128字元。
```
#SBATCH --job-name = test
或是
#SBATCH -J test
```
<!---```
<font錯誤範例
``` --->
7. 工作步驟（Job Steps）：一個Job可以包含一至多個工作步驟（Job Steps），每個job step代表一個獨立的子工作。例如，一個job可能需要進行資料預處理、模型訓練和後處理等多個步驟。在sbatch腳本中或在salloc的shell中，一個srun指令就代表一個工作步驟。
8. 任務 (Tasks)：一個job step可以包含一個或多個tasks，每個task代表一個要在計算節點上執行的工作。在平行計算中，tasks通常用於執行同一個任務的多個實例，從而加速計算的進行。
Slurm指令可使用參數 ==-n, --ntasks=<number>== 指定任務(Tasks)數量。
++不限定在幾個節點(node)上。++
```
#SBATCH --ntasks=200 # Total number of tasks requested
或是
#SBATCH -n 200
```
9. 任務資源 (Task Resource)：指Job在計算節點上執行時所需的資源配置，包括節點數量、每個任務使用的CPU/GPU核心數量和記憶體大小等。以下是幾個與任務資源相關的SLURM常用參數：
(1) -N, --nodes=<minnodes> \[-maxnodes\]：這個參數用於指定Job所需的計算節點數量。<minnodes>是作業所需的最小節點數量，而\[-maxnodes\]是作業所需的最大節點數量。如果只指定了最小節點數量，則Job將在指定的節點數上執行；如果同時指定了最大節點數量，則Slurm將嘗試在節點數量的範圍內動態調整作業的資源分配。
++節點數量根據佇列partition來分類，一個計算節點最多112個cpu核心，依此來判斷你需要哪一個partition。++
(2) -c, --cpus-per-task：這個參數用於指定每個任務（task）所使用的CPU核心數量，當使用多執行緒時才需要設定，預設值為1。透過這個參數，++可以控制每個任務在節點上可使用的CPU核心數。++
(3) --ntasks-per-node\=<ntasks> ：用來指定每個節點上執行的任務數量。透過這個參數，您可以控制每個節點上平行計算的任務數量。若不指定此參數，則任務數量預設值為1，最大值為計算節點的可用CPU核心數。
++一個計算節點最多112個cpu核心，上限不能超過112。++
(4) --gres=gpu:<num>：用於指定Job所需GPU數量的參數，在創進一號中只適用於特定的佇列（Partition），請參考此頁面[Slurm佇列 (Partition)](https://man.twcc.ai/@f1-manual/slurm_instructions)的資訊。
```
#SBATCH --nodes=2 # Total number of nodes requested
#SBATCH --ntasks-per-node=80 # Maximum number of tasks on each node
---
備註:上面範例和下面範例所需要的資源不太相同。
上面是每個節點跑80的task，兩個節點分別跑80個task。
下面是要求跑160個task，沒有限制一個node跑幾個task，可能會依照當時排程系統的資源，舉例一個節點跑滿112個task，另一個節點跑48個task。
#SBATCH -N 2 # Total number of nodes requested
#SBATCH -n 160 # Total number of mpi tasks requested
```
10. 最大執行時間 (Wall Time)：指Job的最大執行時間，也就是Job可以在計算節點上運行的時間限制。由Slurm用來限制作業運行時間，以確保系統資源的有效利用和作業的及時完成。
每個佇列（Partition）皆有限制最大執行時間(Wall Time)，提交Job時，可指定該Job的最大執行時間，++但不能超過佇列（Partition） 預設的最大執行時間(Wall Time)++，請參考此頁面[Slurm佇列 (Partition)](https://man.twcc.ai/@f1-manual/slurm_instructions)的資訊。
Slurm指令可使用參數 -t, --time=<time> 指定該Job的最大執行時間。
時間限制 (days-hrs:min:sec) 可以用不同的單位表示，例如分鐘（time=30表示30分鐘）、小時（time=2:00:00表示2小時）或者天（time=1-00:00:00表示1天）。++如果作業在時間限制內沒有完成，系統將強制終止作業的執行。++
```
#SBATCH --time=2:00:00 # time limit 2 hours
或是
#SBATCH -t 2:00:00
```
11. 寄信通知(mail-type)和收信者(mail-user):五種mail-type(NONE, BEGIN, END, FAIL, ALL)會觸發系統寄信，可以根據你想收到的通知去做選擇。
Slurm指令可使用參數 --mail-type=<mail-type> 和 --mail-user=<user@mail.com.tw> 指定收信者信箱並在特定事件發生時寄出信件。
<font color='red'>備註: 請善用寄信的方式來監控job的狀況!</font>
```
#SBATCH --mail-type=END,BEGIN # Send the mail when the job starts and finishes.
#SBATCH --mail-user=user@gmail.com.tw
```
12. 服務品質 (QOS): 本系統提供兩種關鍵方式影響計算工作: (1)提高排隊優先權、(2)延長計算工作時間。
Slurm指令可使用參數 --qos=<qos> 指定該Job要使用哪一個QOS服務設定。此參數功能需先經過申請，預設上無需加入此參數。
13. 節點狀態 (Node State)：下表列出`sinfo`指令中”STATE”欄位常見的狀態說明。
| 節點狀態 | 描述 |
|-|-|
| idle | 節點處於空閒狀態，沒有任何Job正在運行或排隊等待執行 |
| alloc | 節點已被分配給一個Job，但Job尚未開始執行 |
| mix | 節點同時包含了idle和alloc狀態的資源 |
| comp | 節點上的工作已完成，正在進行清理動作 |
| drain | 節點處於停用狀態，暫時不可用於執行作業 |
| down | 節點處於故障狀態，無法正常工作 |
| fail | 節點上的一個或多個核心或其他組件發生了錯誤或失敗 |
| unknown | 節點的狀態未知，系統無法確定其當前的狀態 |
14. 工作狀態 (Job State)：下表列出`sacct`指令中”STATE”欄位常見的狀態說明。
| 工作狀態 | 描述 |
|-|-|
| COMPLETED | 工作已成功完成 |
| FAILED | 工作執行失敗 |
| CANCELLED | 工作被取消 |
| TIMEOUT | 工作因超時而終止 |
| RUNNING | 工作正在執行中 |
| PENDING | 工作正在等待資源分配 |
| COMPLETING | 工作已完成但正在進行清理工作 |
| NODE_FAIL | 工作由於計算節點失敗而終止 |
| SUSPENDED | 工作處於暫停狀態，等待恢復執行 |
| REQUEUED | 工作被重新排隊等待執行 |
:::
## Slurm常用指令與參數
:::success
<tr>
<td></td>
<td></td>
</tr>
<table>
<tr>
<td>指令</td>
<td>功能說明</td>
</tr>
<tr>
<td>sinfo</td>
<td>查詢佇列(Partitiond)清單與節點狀態 </td>
</tr>
<tr>
<td>squeue</td>
<td > 查詢已提交的Job狀態</td>
</tr>
<tr>
<td>sbatch</td>
<td>(建議)以batch方式提交Job，適合多節點運算。<br>必須指定--account=<PROJECT_ID></br></td>
</tr>
<tr>
<td> srun</td>
<td> 提交Job，直接執行指令且需等待指令執行完成，適合需即時查看輸出的程式除錯工作。</td>
</tr>
<tr>
<td>salloc</td>
<td>提交互動式Job，自動產生一個Shell，離開Shell後Job將自動終止，亦可直接登入Job分配的計算節點，適合用於計算程式開發與除錯工作。
<br>必須指定 --account=<PROJECT_ID></PROJECT_ID></br>
</td>
</tr>
<tr>
<td>squeue</td>
<td>查詢已提交的Job狀態</td>
</tr>
<tr>
<td>scontrol</td>
<td>查詢執行中Job的詳細資訊，如CPU、Memory與節點分配數量</td>
</tr>
<tr>
<td>scancel</td>
<td>停止Job</td>
</tr>
<tr>
<td>sacct</td>
<td>列列出帳號以往執行過的Job與Job steps。若沒指定時間，預設查詢過去24小時的Job清單。</td>
</tr>
</table>
<font color="#f00"> 備註： 萬一登入節點當機時，線上原本使用 ==salloc== 指令提交 job 可能會造成計算中斷或除錯訊息遺失，因此除了除錯或開發用途之外，建議先編輯好job script，然後使用 ==sbatch== 指令提交計算工作。
</font>
1. sinfo
| 指令參數 | 說明 |
|-|-|
| sinfo | 查看partition與節點資訊 |
| sinfo --states=idle | 查看可用(idle)節點資訊 |
| sinfo --partition=<partition> | 查看特定partition資訊 |
| sinfo -N -l | 查詢節點狀態 |
| sinfo --help | 查看所有選項 |
2. squeue
| 指令參數 | 說明 |
|-|-|
| squeue | 查看已提交的Job狀態資訊 |
| squeue -j <job_id> | 查看特定Job資訊 |
| squeue -l | 查看細節資訊 |
| squeue --state=<state> | 查看特定狀態的Job。常用的state有：R(Running)、PD(Pending) |
| squeue --help | 查看所有的選項 |
3. scontrol
| 指令參數 | 說明 |
|-|-|
| scontrol show job <job_id> | 查看排隊或正在運行的Job詳細資訊 |
| scontrol show node <node> | 查看計算節點可用資源規格 |
4. scancel
| 指令參數 | 說明 |
|-|-|
| scancel <job_id> | 刪除Job |
| scancel -i -u $UID | 互動式詢問刪除用戶自己的Job |
5. sacct
| 指令參數 | 說明 |
|-|-|
| sacct | 列出過去24小時內結束的Job清單 |
| sacct -j <job_id> | 列出指定的已結束Job |
| sacct --starttime $(date -d "7 days ago" +%Y-%m-%d) | 列出過去7天內結束的Job清單 |
| sacct --help | 查看所有的選項 |
:::
<!---<font color="red">
shell 適用c語言編寫。
容許的字元為 A-Z、a-z、0-9、底線、連字號。
不接受空格。
開頭不可以 # ' :
開頭可以 ， ! . ^ & ? * < > / @ ~
' " 單一個部型 雙夾住字元可以
\ 反斜線會消失
長度限制 256個位元
- **Allowed Characters**: Generally, you should use alphanumeric characters, underscores (_), and hyphens (-). Special characters like `#` or spaces should be avoided or used with caution as they might cause issues.
- **Length**: Some SLURM implementations may have a maximum length for job names, typically around 256 characters.
</font>--->