9.1.1 HTCondor 作业¶

9.1.1.1 说明¶

HTCondor 是一款在高能物理计算领域较流行的开源批处理系统，支持大规模计算集群，具有较高灵活性，特别适用于高通量作业调度。计算中心已将绝大部分本地资源迁移归属于 HTCondor 管理。根据计算集群的实际情况，计算中心对 HTCondor 进行了配置与优化，并开发部署了 HepJob 工具集帮助用户管理作业。HepJob 中包装了针对高能所集群的优化，若非特殊需求，用户 应当使用 HepJob 而非 HTCondor 原生命令 。

9.1.1.2 HepJob 工具集¶

环境设置和作业准备¶

HepJob涉及的所有命令都在以下目录，建议将该目录加入用户环境变量 PATH 中：

bash 用户

export PATH=/cvmfs/common.ihep.ac.cn/software/hepjob/bin:$PATH

tcsh 用户

setenv PATH /cvmfs/common.ihep.ac.cn/software/hepjob/bin:$PATH

提交 HTCondor 计算集群的作业文件必须具备可执行权限。可使用以下命令查看和赋予文件权限：

查看文件权限

/bin/ls -l job.sh
# 输出：-rw-r--r-- 1 jiangxw u07 85 Aug 29 18:23 job.sh

上面的例子中 job.sh 不具有可执行权限，执行如下命令可赋予文件可执行权限

/bin/chmod +x job.sh

再次查询，首列输出信息中多出的 x 表示可执行权限

/bin/ls -l job.sh
# 输出：-rwxr-xr-x 1 jiangxw u07 85 Aug 29 18:23 job.sh

作业提交¶

命令格式：

hep_sub [-h] [-g {physics,juno,dybrun,dyw,u07,offlinerun,pku,longq}]
             [-p {virtual,local,ali}] [-u {vanilla,grid,docker}] [-o OUT]
             [-e ERROR] [-n NUMBER] [-os OPERATINGSYSTEM]
             [-t {atlasbm,hxmtbm,wljMC}] [-prio PRIORITY]
             [-np NUMBERPROCESS] [-argu ARGUMENTS [ARGUMENTS ...]]
             [-dir DIRECTORY] [-mem MEMORY] [-quiet] [-part PARTITION]
             [-name NAME] [-slurm] [-site SITENAME] [-jf JOBFILE]
             [-tf TRANSFERFILE] [-wn WORKNODE] [-wt WALLTIME]
             jobscript

常用参数说明：

jobscript：作业脚本名，可以是绝对路径文件名也可以是相对路径文件名。使用示例

hep_sub job.sh

-g：指定作业的用户组，不设置时默认为用户的主组。以使用 juno 组的计算资源为例

hep_sub -g juno job.sh

-p：指定资源池。当前提供两类资源池：local 物理机资源池和 virtual 虚拟机资源池。不指定时默认为 local 物理资源池。以使用虚拟资源池为例

hep_sub -p virtual job.sh

-u：指定作业类型。如果不指定则默认为vanilla。本地集群的大部分用户无需指定此参数，如果需要运行网格作业，则指定为 -u grid。示例如下

hep_sub -u grid job.sh

-o：指定作业运行的标准输出文件路径，不指定时默认在当前目录下产生一个文件名为 作业名+.out 的标准输出文件。
-e：指定作业运行的标准报错文件，不指定时默认在当前目录下产生一个文件名为 作业名+.err 的标准报错文件。
-l：指定作业日志文件路径，不指定时默认不产生。日志文件是指作业运行状态日志，一般情况下对普通用户没有意义。
-os：指定作业需要的操作系统版本，不指定时默认为 SL6。假设用户作业希望使用 SL7 系统的资源，则命令格式为

hep_sub -os SL7 job.sh

-np：指定申请的资源核数，在运行 mpi 作业时需要设定。
-argu：指定作业脚本参数。例如，作业执行程序参数为 1，则命令格式为

hep_sub -argu 1 job.sh

-mem：指定作业所需内存大小，单位为 MB。例如，使用 3G 以上内存，则命令格式为

hep_sub -mem 3000 job.sh

如果只有-mem，则作业将被调度到最大内存的机器上运行。

-site：指定作业运行到远程站点。
便捷参数：除了上述的基本参数，为了简化用户提交作业命令，hep_sub 还为不同实验准备了不同作业模板，（目前提供 cepcmpi 模板，其它实验的模板将会逐步增加）。使用参数-t指定相应的模板，例如想要提交 cepc 的 mpi 作业，示例如下

hep_sub -t cepcmpi job.sh

注意

在使用 -t 参数同时又使用其他参数，可能会影响 -t 模板的使用。

作业状态查询¶

命令格式：

hep_q [-h] [-u [USER]] [-i ID] [-run] [-p {virtual,local,ali}]
      [-t {atlasbm,hxmtbm,wljMC}] [-st STARTTIME]
      [-stat {run,idle,other} [{run,idle,other} ...]] [-slurm]

常用参数说明：

-u：指定查看某用户的作业，默认为当前用户。示例如下

hep_q -u <username>

执行 hep_q -u 而不指定用户名，将输出当前用户的作业信息。

-i：指定特定作业 clusterid 或完整作业号，无默认值。作业系统作业号由 clusterid 和 processid 两部分构成，clusterid 为作业簇的编号，而 processid 为作业簇内部编号，完整作业号格式为 clusterid.processid（如作业 3745232.1，clusterid 为 3745232，processid 为 1）。以查询作业号为 3745232.1 的作业为例

hep_q -i 3745232.1

而查询作业簇号为 3745232 的所有作业时，省略作业簇内部编号

hep_q -i 3745232

-run：查询正在运行的作业信息，不加参数时输出所有作业信息。输出格式示例

JOBID OWNER SUBMITTED RUN_TIME ST PRI SIZE CMD
5519.0 user1 04/11 15:11 0+00:00:00 I 0 0.0 myjob.sh
3656.0 user2 04/11 17:12 0+00:00:00 I 0 0.1 job.sh

其中 JOBID 表示作业号，OWNER 表示作业所属用户，SUBMITTED 表示作业提交时间，RUN_TIME 表示作业运行时间，ST 表示作业当前状态，PRI 表示作业优先级，SIZE 表示作业占用虚拟内存大小，CMD 表示作业程序名。

-t：选择指定模板，例如 cepcmpi 用户在查询作业时需添加该参数

hep_q -i 3745232 -t cepcmpi

作业删除¶

命令格式：

hep_rm [-h] [-a] [-forcex] [-p {virtual,physical}] [-site SITENAME]
       [-t {atlasbm,hxmtbm,wljMC}] [-name NAME] [-slurm]
       [jobs [jobs ...]]

常用参数说明：

jobs：指定要删除的作业 id，支持指定多个作业 id 同时删除。例如

hep_rm 3745232 3745233.0

该命令删除作业簇 3745232 内所有作业，以及作业号为 3745233.0 的作业。

-a：删除当前用户所有作业，示例如下

hep_rm -a

-t：选择指定模板，例如 cepcmpi 用户在删除作业时需添加该参数

hep_rm 3745232 -t cepcmpi

-forcex：强制删除 'X' 状态作业，注意，该参数只用于删除 'X' 状态作业。'X' 状态作业一般由于节点故障等导致计算节点与调度服务器不能正常释放连接，作业处于删除状态。可指定作业 ID 或配合 -a 参数使用。例如，如果作业 3745232 处于 'X' 状态，可用如下命令删除：

hep_rm 3745232 -forcex

其它¶

HepJob 所有命令提供 -h 和 --help 参数，用于查看命令说明。

9.1.1.3 作业及资源信息¶

作业时长及运行数限制¶

在登录节点上，可运行命令，按组查看作业时长限制。如查看 juno 组的作业时长限制，运行：

hep_clus -g juno --walltime

实验	短作业（short）时长限制（小时）	普通作业时长限制（小时）	mid 作业时长限制（小时）及资源使用量限制（百分比）
BES	<0.5	<40	<100:10%
JUNO	<0.5	<20	<100:10%
DYW	<0.5	<10	<100:10%
CEPC	<0.5	<10	<100:10%
ATLAS	<0.5	<10	<100:10%
CMS	<0.5	<10	<100:10%
HXMT	<0.5	<14	<100:10%
GECAM	<0.5	<24	<100:10%
LHCb	<0.5	<100	—
LHAASO	<0.5	<15	<100:10%

注意：未设置 mid 作业的实验，默认提交 mid 作业时，资源使用量限制为 1。

9.1.1.4 使用技巧¶

“宏”在作业提交中的应用¶

“宏”是由调度系统提供，可以在作业提交时，由用户定义一系列规则。目前只提供基本的变量传递功能，可使用变量传递的参数为 [jobscript, -o, -e, -argu]。变量传递的语法由百分号"%"和大括号"{}"构成，示例如下：

%{macro_name}

较适用的使用场景为批量作业提交，具体方法参考第 2 小节。此外，如将作业号、组名等加入到作业文件命名等要求也可使用"宏"来实现。详细功能后续加入。

批量作业提交¶

批量作业提交，即一次性提交多个作业，可支持一次性提交大量的作业。参数 -n 指定一次性批量提交的作业数量。批量命令格式如下：

hep_sub job.sh."%{ProcId}" -n 5000

其中，%{ClusterId} 为作业簇号；%{ProcId} 为作业簇内部编号，该编号由 0 开始以 1 的步长逐渐递增（0、1、2、3……），因此，可以使用 %{ProcId} 将作业与作业输出对应起来，也可自定义输出。作业脚本可使用与 %{ProcId} 对应的后缀或前缀等子字符串区分。

同时，也可以把 %{ProcId} 作为参数传递给作业脚本，可以利用这个参数映射其他对应的文件（如输入数据文件等）。命令如下：

hep_sub job.sh -argu "%{ProcId}" -n 5000

注意

批量提交作业时，确保作业脚本存在并且具有可执行权限。此外，避免误操作提交过大数量的作业，大量使用资源会影响自己的作业优先级。

示例1：先准备好要提交作业的脚本，并保证作业脚本有可执行权限，如下：

real_job_20191204_0.sh
real_job_20191204_10.sh
real_job_20191204_1.sh
real_job_20191204_2.sh
real_job_20191204_3.sh
real_job_20191204_4.sh
real_job_20191204_5.sh
real_job_20191204_6.sh
real_job_20191204_7.sh
real_job_20191204_8.sh
real_job_20191204_9.sh

因为这些作业脚本名字里都是这类格式 real_job_20191204_*.sh，且关键字符是从 0 开始递增的数字，提交这些作业只需要运行：

hep_sub real_job_20191204_"%{ProcId}".sh -n 11

示例2：如果作业脚本名字里没有以从 0 开始的递增数字，而是其他格式，但仍有规律可寻。如下：

real_job_20191201.sh
real_job_20191202.sh
real_job_20191203.sh
real_job_20191204.sh
real_job_20191205.sh
real_job_20191206.sh
real_job_20191207.sh
...
real_job_20191230.sh
real_job_20191231.sh

可以额外准备一个作业脚本，将 %{ProcId} 作为参数传递给该脚本，在脚本里做处理映射到这些文件。例如，针对上面的作业程序，脚本名的结尾是日期，准备脚本 real_job_parent.sh：

#!/bin/bash

# get procid from command line
procid=$1

# map 0,1,2,...,30 to 1,2,3,...,31
sub_name_number=`expr $procid + 1`

# format 1,2,3,...,31 to 01,02,03,...,31
sub_name=`printf "%02d\n" $sub_name_number` 

# run the real job script by the formatted file name
bash real_job_201912"${sub_name}".sh

运行命令提交作业：

hep_sub real_job_parent.sh -argu "%{ProcId}" -n 31

作业程序中获取作业基本信息¶

作业ID（作业号）

从作业程序中获取作业号：作业号可以通过 _CONDOR_IHEP_JOB_ID 环境变量获取。注意，此环境变量只在该作业运行期间有效。以 bash 脚本为例，获取该环境变量如下

  #!/bin/bash
  JobId=$_CONDOR_IHEP_JOB_ID

作业运行节点

以 bash 脚本为例，通过环境变量 _CONDOR_IHEP_REMOTE_HOST，获取作业运行节点信息如下：

  #!/bin/bash
  ExecWorkNode=$_CONDOR_IHEP_REMOTE_HOST

作业提交时间

以 bash 脚本为例，通过环境变量 _CONDOR_IHEP_SUBMISSION_TIME，获取作业提交时间信息如下：

  #!/bin/bash
  SubmissionTime=$_CONDOR_IHEP_SUBMISSION_TIME

9.1.1.5 对各实验使用方式的建议和说明¶

BESIII 实验¶

如果提交标准的 boss 作业，可使用更简化的 boss.condor 命令：

boss.condor joboptions.txt

如果用户需要指定作业内存大小，可以使用参数 -mem：

boss.condor -mem 5000 joboptions.txt

如果用户需要使用多个 CPU 核，可以使用参数 -cpu：

boss.condor -cpu 2 joboptions.txt

如果用户想要调整作业的最大运行时间，可以使用参数 -wt：

boss.condor -wt mid joboptions.txt

注意：我们提供了如下的作业类型：test、short、mid、long、special。

如果用户想要提交一批作业号连续的作业，可以使用参数 -n：

# 假设存在用户作业：job0、job1、job2，可以利用 -n 和 "%{ProcId}" 来进行批量提交

boss.condor -n 3 job%"{ProcId}"

# 这里的 "{ProcId}" 替代作业号中从 0 开始的数字，在此之前需添加 %，用这样的方式可以一次性提交 job0、job1、job2 三个作业。

注意：作业号须从 0 开始。

boss.condor 现支持作业的"一条龙"服务（将 SIM 和 REC 打包成一个整体的作业），可以使用如下命令：

boss.condor sim_joboption.txt rec_joboption.txt ana_joboption.txt

一次提交，即可完成三个作业。

同样，"一条龙"服务支持批量提交的功能。

# 假设存在用户作业：sim0、rec0、ana0、sim1、rec1、ana1

boss.condor -n 2 sim%"{ProcId}" rec%"{ProcId}" ana%"{ProcId}"

# 此语法会提交两个用户作业，第一个作业为 sim0、rec0、ana0，第二个作业为 sim1、rec1、ana1

BESIII 用户若提交其它作业，请设置用户组为 physics：

hep_sub -g physics job.sh

作业查询和删除参考上一小节内容。

CEPC MPI 作业¶

提交 MPI 作业参考样例：

hep_sub /cefs/CEPCMPI/username/mpijob.sh -g cepcmpi -t cepcmpi -np 20

其中，-t 指 cepcmpi 实验作业，-np 为申请的核数，要求提供作业脚本的全路径。

作业查询和删除参考上一小节内容。

COMET 作业¶

作业提交、查询和删除参考 BESIII 实验。

无特殊说明的其它实验¶

参考上一小节内容。

常见问题（FAQ）¶

见常见问题。

🤖 AI 助手