cbatch - 提交批处理作业¶

cbatch 主要是将用户描述整个计算过程的脚本传递给作业调度系统，并为作业分配作业号，等待作业调度系统为其分配资源并执行。

鹤思系统中必须有用户和账号才能提交作业，添加用户和账户请参考 cacctmgr 教程。

快速开始¶

首先介绍一个简单的单节点作业的例子：

下列作业将申请一个节点，一个 CPU 核心，并在计算节点上运行 hostname 并退出

#!/bin/bash
#CBATCH --ntasks-per-node 1
#CBATCH --nodes 1
#CBATCH -c 1
#CBATCH --mem 20M
#CBATCH --time 0:3:1
#CBATCH -o job.out
#CBATCH -p CPU
#CBATCH -J Test_Job

hostname

假设上面作业脚本的文件名为 cbatch_test.sh，通过 cbatch 命令提交：

cbatch cbatch_test.sh

cbatch 运行结果展示

cbatch

命令行选项¶

资源规格¶

-N, --nodes uint32: 作业要运行的节点数量（默认值：1）
-c, --cpus-per-task float: 每个任务所需的 CPU 核心数（默认值：1）
--ntasks-per-node uint32: 每个节点要调用的任务数量（默认值：1）
--mem string: 最大实际内存量，支持 GB（G，g）、MB（M，m）、KB（K，k）和字节（B），默认单位是 MB
--gres string: 每个任务所需的通用资源，格式：gpu:a100:1 或 gpu:1
--L, --licenses: 作业要使用的许可证，格式：lic1:2,lic2:4或lic1:2|lic2:4

作业信息¶

-J, --job-name string: 作业名称
-A, --account string: 提交作业的账户
-p, --partition string: 请求的分区
-q, --qos string: 作业使用的服务质量（QoS）
-t, --time string: 时间限制，格式：day-hours:minutes:seconds（如 5-0:0:1 表示 5 天 1 秒）或 hours:minutes:seconds（如 10:1:2 表示 10 小时 1 分钟 2 秒）
--comment string: 作业注释

节点选择¶

-w, --nodelist string: 要分配给作业的节点（逗号分隔的列表）
-x, --exclude string: 从分配中排除特定节点（逗号分隔的列表）

I/O 重定向¶

-o, --output string: 脚本标准输出的重定向路径
-e, --error string: 脚本错误日志的重定向路径
--open-mode string: 打开输出和错误文件的模式。支持的值：append（追加）、truncate（截断，默认）

环境变量¶

--get-user-env: 加载用户的登录环境变量
--export string: 传播环境变量

调度选项¶

--begin string: 作业的开始时间。格式：YYYY-MM-DDTHH:MM:SS
--exclusive: 请求独占节点资源
-H, --hold: 以挂起状态提交作业
-r, --reservation string: 使用预留资源

邮件通知¶

--mail-type string: 当特定事件发生时，向用户发送邮件通知。支持的值：NONE、BEGIN、END、FAIL、TIMELIMIT、ALL（默认：NONE）
--mail-user string: 通知接收者的邮件地址

容器支持¶

--container string: 容器镜像的路径
--interpreter string: 指定脚本解释器（如 /bin/bash、/usr/bin/python3）

其他选项¶

-D, --chdir string: 作业的工作目录
--extra-attr string: 作业的额外属性（JSON 格式）
--repeat uint32: 多次提交作业（默认值：1）
--wrap string: 将命令字符串包装到 shell 脚本中并提交
--json: 以 JSON 格式输出
-C, --config string: 配置文件路径（默认：/etc/crane/config.yaml）
-h, --help: 显示帮助信息
-v, --version: 显示 cbatch 版本

使用示例¶

基本作业提交¶

提交批处理脚本：

cbatch cbatch_test.sh

帮助信息¶

显示帮助：

cbatch -h

指定账户¶

使用特定账户提交作业：

cbatch -A=acct-test cbatch_test.sh

节点排除¶

从分配中排除节点：

cbatch -x crane01,crane02 cbatch_test.sh

作业名称¶

指定作业名称：

cbatch -J testjob01 cbatch_test.sh

节点选择¶

请求特定节点：

cbatch -w crane01,crane03 cbatch_test.sh

分区选择¶

提交到特定分区：

cbatch -p GPU cbatch_test.sh

时间限制¶

设置时间限制：

cbatch -t 00:25:25 cbatch_test.sh

CPU 核心¶

请求特定数量的 CPU 核心：

cbatch -c 2 cbatch_test.sh

内存规格¶

指定内存需求：

cbatch --mem 123M cbatch_test.sh

多节点作业¶

请求多个节点并指定每个节点的任务数：

cbatch -N 2 --ntasks-per-node 2 cbatch_test.sh

工作目录¶

指定工作目录：

cbatch -D /path test.sh

错误日志¶

重定向错误输出：

cbatch -e error.log test.sh

环境变量¶

导出所有环境变量：

cbatch --export ALL test.sh

用户环境¶

加载用户的登录环境：

cbatch --get-user-env test.sh

输出重定向¶

重定向标准输出：

cbatch -o output.out test.sh

服务质量¶

指定 QoS：

cbatch -q qos_test test.sh

重复提交¶

多次提交作业：

cbatch --repeat 3 test.sh

环境变量¶

批处理脚本中可用的常用环境变量：

变量	说明
CRANE_JOB_NODELIST	作业分配的节点列表
%j	作业号（用于文件模式）

多节点并行作业¶

下面介绍提交一个跨节点多核心的例子：

下列作业将在三个节点上运行，每个节点使用 4 个 CPU 核心：

#!/bin/bash
#CBATCH -o crane_test%j.out
#CBATCH -p CPU
#CBATCH -J "crane_test"
#CBATCH --nodes 3
#CBATCH --ntasks-per-node 4
#CBATCH -c 4
#CBATCH --time 50:00:00

# 生成作业分配的节点的 machinefile
echo "$CRANE_JOB_NODELIST" | tr ";" "\n" > crane.hosts

# 加载 MPI 运行环境
module load mpich/4.0 

# 执行跨节点并行任务
mpirun -n 13 -machinefile crane.hosts helloWorld > log

高级功能¶

容器支持¶

提交在容器中运行的作业：

cbatch --container /path/to/container.sif my_script.sh

延迟启动¶

将作业调度到特定时间启动：

cbatch --begin 2024-12-31T23:00:00 my_script.sh

挂起作业¶

以挂起状态提交作业：

cbatch --hold my_script.sh

使用 ccontrol release <job_id> 释放挂起的作业。

邮件通知¶

接收电子邮件通知：

cbatch --mail-type=ALL --mail-user=user@example.com my_script.sh

JSON 输出¶

以 JSON 格式获取提交结果：

cbatch --json my_script.sh

包装命令¶

提交简单命令而无需创建脚本文件：

cbatch --wrap "echo Hello && sleep 10 && echo Done"

另请参阅¶

cqueue - 查看作业队列
ccancel - 取消作业
cacct - 查看作业统计信息
ccontrol - 控制作业和系统资源