SPANK plugin สำหรับ QRMI

SPANK plugin สำหรับ Quantum Resource Management Interface (QRMI) ใช้สำหรับกำหนดค่าการเข้าถึงทรัพยากรควอนตัมจาก user job ในสภาพแวดล้อมการประมวลผลที่ดูแลโดย Slurm workload manager โดยจัดการการรับและการคืนสิทธิ์การเข้าถึงทรัพยากรควอนตัม และตั้งค่า environment variable ที่จำเป็นสำหรับการรัน quantum workload ทรัพยากรควอนตัมที่มีอยู่ถูกระบุในไฟล์ qrmi_config.json ซึ่งจัดการโดยผู้ดูแลระบบ

เมื่อติดตั้งแล้ว plugin นี้จะลงทะเบียนตัวเลือกต่อไปนี้ ผู้ใช้ Slurm สามารถระบุว่าจะใช้ quantum resource ใดสำหรับ Slurm job script

--qpu=names             Comma separated list of QPU resources to use.

ตัวอย่างเช่น:

#!/bin/bash

#SBATCH --job-name=sampler_job
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=1
#SBATCH --qpu=ibm_quebec,ibm_sherbrooke

# Your script goes here...

ข้อกำหนดและการกำหนดค่า

ต้องใช้เครื่องมือต่อไปนี้สำหรับสภาพแวดล้อมการคอมไพล์:

• Rust compiler 1.86 ขึ้นไป
• C compiler: เช่น GCC (gcc) บน Linux และ Clang (clang-tools-extra) สำหรับ Rust unknown targets/cross compilation QRMI และ SPANK plugin รองรับ compiler ที่สอดคล้องกับมาตรฐาน C11
• make/cmake (make/cmake RPM สำหรับ RHEL-compatible OS)
• openssl (openssl-devel RPM สำหรับ RHEL-compatible OS)
• zlib (zlib-devel RPM สำหรับ RHEL-compatible OS)
• Slurm header file (slurm/slurm.h และอื่นๆ) ต้องมีอยู่บน host ของคุณ

สภาพแวดล้อม runtime ต้องการ:

• gcc (libgcc RPM สำหรับ RHEL-compatible OS)
• openssl (openssl-libs RPM สำหรับ RHEL-compatible OS)
• zlib (zlib RPM สำหรับ RHEL-compatible OS)

กำหนดค่าทรัพยากรควอนตัมที่มีอยู่

repository มีตัวอย่างการกำหนดค่า (qrmi_config.json.example)

array resources ประกอบด้วยชุดของ quantum resource ที่มีอยู่ แต่ละ quantum resource definition ประกอบด้วยสิ่งต่อไปนี้:

Property	คำอธิบาย
name	ชื่อ quantum resource (เช่น backend name)
type	ประเภท resource (direct-access, qiskit-runtime-service และ pasqal-cloud)
environment	ชุดของ environment variable สำหรับทำงานกับ QRMI การใช้งานปัจจุบันถือว่า API endpoint และ credentials ถูกระบุผ่านการตั้งค่า environment variable

หากผู้ใช้ระบุ resource ด้วยตัวเลือก --qpu ที่ไม่ได้กำหนดไว้ในไฟล์ qrmi_config.json การระบุนั้นจะถูกละเว้น

หากผู้ใช้ตั้งค่า environment variable ที่จำเป็นสำหรับการรัน job เอง ก็ไม่จำเป็นต้องระบุในไฟล์นี้ ในกรณีนี้ property environment จะเป็น {}

หมายเหตุ

หากคุณใช้ QPU resource ที่มีประเภท resource เป็น qiskit-runtime-service ให้ใช้บัญชีที่รองรับ การเปิด session เช่น บัญชี Premium Plan

หากคุณใช้บัญชีที่ไม่รองรับการเปิด session เช่น บัญชี Open Plan ให้เพิ่ม QRMI_IBM_QRS_SESSION_MODE="batch" ลงในรายการ environment variable ใน qrmi_config.json เป็น workaround

การติดตั้ง

รัน build โดยใช้ make และ cmake:

. ~/.cargo/env
mkdir build
cd build
cmake ..
make

โดยค่าเริ่มต้น ไฟล์ CMakeLists.txt คาดว่า Slurm header file (slurm.h) จะอยู่ที่ /usr/include/slurm แต่สามารถกำหนดเองได้ตามที่แสดงด้านล่าง

SLURM_INCLUDE_DIRS=<directory containing slurm/slurm.h> cmake ..

หากขั้นตอน build ข้างต้นสำเร็จ Linux shared library ชื่อ spank_qrmi.so จะถูกสร้างภายใต้ไดเรกทอรี build/

นอกจากนี้ ให้เพิ่มบรรทัดต่อไปนี้หนึ่งบรรทัดใน /etc/slurm/plugstack.conf บนโหนดที่ติดตั้ง plugin นี้ (หมายเหตุ: ผู้ดูแลระบบต้องสร้างไฟล์ qrmi_config.json และระบุ path เป็น plugin argument ตามที่แสดงด้านล่าง):

optional /usr/lib64/slurm/spank_qrmi.so /etc/slurm/qrmi_config.json

หมายเหตุ

คุณสามารถใช้ optional argument ที่มีอยู่เพื่อเพิ่ม environment variable ไปยัง Slurm process ที่โหลด SPANK plugin รูปแบบสำหรับระบุ environment variable มีการกำหนดดังนี้:

--env:{variable name}={value}

ตัวอย่างเช่น เมื่อโต้ตอบกับ quantum resource ผ่าน HTTP proxy จำเป็นต้องใช้ environment variable http_proxy, https_proxy และ no_proxy สามารถเพิ่มได้ตามที่แสดงด้านล่าง:

optional /usr/lib64/slurm/spank_qrmi.so /etc/slurm/qrmi_config.json --env:http_proxy=http://192.168.1.128:3128 --env:https_proxy=http://192.168.1.128:3128

สำหรับ allocator node ไม่จำเป็นต้องระบุ path ไปยัง qrmi_config.json ตามที่แสดงด้านล่าง:

optional /usr/lib64/slurm/spank_qrmi.so

ตารางต่อไปนี้แสดงว่าไฟล์เหล่านี้ควรคัดลอกไปยัง Slurm context โหนดใด สำหรับรายละเอียดเพิ่มเติมของแต่ละ context ให้ดูที่ เอกสาร ของ SPANK plugin

ไฟล์	Slurm contexts
plugstack.conf	local, remote, allocator, slurmd และ job_script
qrmi_config.json	remote (Compute nodes)
spank_qrmi.so	allocator และ remote (Login nodes และ compute nodes)

หมายเหตุ

เมื่ออัปเดต plugstack.conf แล้ว SPANK plugin จะถูกโหลดที่รันไทม์ในระหว่างการเปิด job ครั้งถัดไป ซึ่งหมายความว่าผู้ดูแลระบบไม่จำเป็นต้องรีสตาร์ท Slurm cluster

เมื่อการติดตั้งเสร็จสมบูรณ์ คุณจะพบตัวเลือก --qpu=names ในข้อความช่วยเหลือของ sbatch

Options provided by plugins:
      --qpu=names             Comma-separated list of QPU resources to use.

การบันทึก log

Plugin นี้ใช้ Slurm logger สำหรับการบันทึก log ข้อความ log จาก plugin นี้สามารถพบได้ใน /var/log/slurm/slurmd.log

[2025-07-31T09:43:34.019] [21.batch] debug:  spank: /etc/slurm/plugstack.conf:1: Loaded plugin spank_qrmi.so
[2025-07-31T09:43:34.019] [21.batch] debug:  spank_qrmi_c(6582, 0): -> slurm_spank_init argc=1 remote=1
[2025-07-31T09:43:34.019] [21.batch] debug:  SPANK: appending plugin option "qpu"
[2025-07-31T09:43:34.019] [21.batch] debug:  spank_qrmi_c(6582,0): <- slurm_spank_init rc=0
[2025-07-31T09:43:34.019] [21.batch] debug2: spank: spank_qrmi.so: init = 0
[2025-07-31T09:43:34.019] [21.batch] debug:  spank_qrmi_c: --qpu=[ibm_sherbrooke,ibm_torino]
[2025-07-31T09:43:34.019] [21.batch] debug:  spank_qrmi_c(6582, 0): -> slurm_spank_init_post_opt argc=1 remote=1
[2025-07-31T09:43:34.019] [21.batch] debug:  spank_qrmi_c, fffffffb
[2025-07-31T09:43:34.019] [21.batch] debug:  spank_qrmi_c: argv[0] = [/etc/slurm/qrmi_config.json]
[2025-07-31T09:43:34.020] [21.batch] debug:  spank_qrmi_c: name(ibm_sherbrooke), type(1) found in qrmi_config

คุณสามารถเปิดใช้งาน QRMI runtime log โดยระบุ argument ของ srun ต่อไปนี้

ตัวเลือก sbatch/srun	ระดับ log ของ Slurm (SRUN_DEBUG)	ระดับ log ของ QRMI (RUST_LOG)
(ค่าเริ่มต้น)	3	info
--quiet	2	error
--verbose	4	debug
-vv ขึ้นไป	5	trace

ข้อพิจารณาสำหรับ QPU หลายตัว

ในระหว่างรันไทม์ แต่ละ QRMI instance เชื่อมโยงกับ QPU resource เดียว เพื่อให้สามารถใช้ quantum resource หลายตัวใน job script เดียวได้ plugin นี้จะตั้งค่า environment variable โดยใช้ชื่อ resource เป็น prefix ตัวอย่างเช่น หากระบุ --qpu=qpu1,qpu2 environment variable จะถูกตั้งค่าดังนี้:

qpu1_QRMI_IBM_DA_ENDPOINT=http://test1
qpu2_QRMI_IBM_DA_ENDPOINT=http://test2

ซึ่งทำให้แน่ใจว่าแต่ละ QRMI instance ทำงานด้วยพารามิเตอร์การกำหนดค่าที่ตั้งไว้สำหรับ resource ของตนเองในระหว่างการรัน Slurm job

การตั้งค่า environment variable ข้างต้นจะใช้เฉพาะกับ job ที่ระบุตัวเลือก --qpu=names เท่านั้น

Plugin นี้ยังตั้งค่า environment variable สองตัวต่อไปนี้ ซึ่งถูกอ้างอิงโดยโค้ด QRMI primitives

Environment variable	คำอธิบาย
SLURM_JOB_QPU_RESOURCES	รายชื่อ QPU resource ที่คั่นด้วยเครื่องหมายจุลภาคสำหรับใช้งานในรันไทม์ resource ที่ไม่ได้บันทึกจะถูกกรองออก เช่น qpu1,qpu2
SLURM_JOB_QPU_TYPES	รายการประเภท resource ที่คั่นด้วยเครื่องหมายจุลภาค (direct-access, qiskit-runtime-service และ pasqal-cloud) เช่น direct-access,pasqal-cloud