科研 Skill
SLURM作业脚本生成
slurm-job-script-generator
Generates correct SLURM sbatch job scripts and sanity-checks HPC resource requests: nodes, MPI/OpenMP layout, memory, GPUs, walltime. Use when writing or debugging a SLURM submission script.
SKILL.md
SLURM Job Script Generator
Goal
Generate a correct, copy-pasteable SLURM job script (.sbatch) for running a simulation, and surface common configuration mistakes (bad walltime format, conflicting memory flags, oversubscription hints).
Requirements
- Python 3.10+
- No external dependencies (Python standard library only)
- Works on Linux, macOS, and Windows (script generation only)
Inputs to Gather
| Input | Description | Example |
|---|---|---|
| Job name | Short identifier for the job | phasefield-strong-scaling |
| Walltime | SLURM time limit | 00:30:00 |
| Partition | Cluster partition/queue (if required) | compute |
| Account | Project/account (if required) | matsim |
| Nodes | Number of nodes to allocate | 2 |
| MPI tasks | Total tasks, or tasks per node | 128 or 64 per node |
| Threads | CPUs per task (OpenMP threads) | 2 |
| Memory | --mem or --mem-per-cpu (cluster policy dependent) | 32G |
| GPUs | GPUs per node (optional) | 4 |
| Working directory | Where the run should execute | $SLURM_SUBMIT_DIR |
| Modules | Environment modules to load (optional) | gcc/12, openmpi/4.1 |
| Run command | The command to launch under SLURM | ./simulate --config cfg.json |
Decision Guidance
MPI vs MPI+OpenMP layout
Does the code use OpenMP / threading?
├── NO → Use MPI-only: cpus-per-task=1
└── YES → Use hybrid: set cpus-per-task = threads per MPI rank
and export OMP_NUM_THREADS = cpus-per-task
Rule of thumb: if you see diminishing strong-scaling efficiency at high MPI ranks, try fewer ranks with more threads per rank (and measure).
Memory flag selection
- Use either
--mem(per node) or--mem-per-cpu(per CPU), not both. - Follow your cluster’s documentation; some sites enforce one style.
- SLURM
--memunits are integer MB by default, or an integer with suffixK/M/G/T(and--mem=0commonly means “all memory on node”).
Launcher selection (avoid double-wrapping)
- By default (
--launcher srun) the generator prependssrun --ntasks=N --cpus-per-task=Tto your run command so it inherits SLURM task placement. - If your run command already starts with
srun,mpirun, ormpiexec, pass--launcher noneso the generator does not double-wrap it. Wrappingsrunaroundmpirunlaunches N independent copies ofmpirun(each spawning its own MPI world); wrappingsrunaroundsrunis malformed. - As a safety net, the generator auto-detects a leading launcher (
srun,mpirun,mpiexec,mpiexec.hydra,orterun,aprun,jsrun) and falls back to no-wrap, emitting a warning that recommends--launcher none.
GPU layout
- Ranks-per-GPU =
total_ranks / (nodes * gpus_per_node). When--gpus-per-nodeis set the generator reportsresults.derived.total_gpusandresults.derived.ranks_per_gpu. - Aim to map ranks evenly to devices. If
ntasksis not divisible by the total number of GPUs, the generator emits a "task-to-GPU ratio is not an integer" warning; either adjustntasks/GPUs or document intentional sharing (e.g. NVIDIA MPS). - Consider binding options such as
--gpu-bind=closestor--ntasks-per-gpu(passed via your run command /--srun-extra). GPU and QoS policies are site-specific — confirm with your cluster docs.
Script Outputs (JSON Fields)
| Script | Key Outputs |
|---|---|
scripts/slurm_script_generator.py | results.script, results.directives, results.derived, results.warnings, results.run_line |
results.derived reports ntasks, ntasks_per_node, cpus_total_requested, and (when applicable) cores_per_node, cpus_per_node_requested, total_gpus, and ranks_per_gpu. results.warnings may include CPU oversubscription, task-to-GPU ratio, and double-launcher warnings.
Workflow
- Gather cluster constraints (partition/account, GPU policy, memory policy).
- Choose a process layout (MPI-only vs hybrid MPI+OpenMP).
- Generate the script with
slurm_script_generator.py. - Inspect warnings (conflicts, suspicious layouts).
- Save the generated script as
job.sbatch. - Submit with
sbatch job.sbatchand monitor withsqueue.
CLI Examples
# Preview a job script (prints to stdout)
python3 skills/hpc-deployment/slurm-job-script-generator/scripts/slurm_script_generator.py \
--job-name phasefield \
--time 00:10:00 \
--partition compute \
--nodes 1 \
--ntasks-per-node 8 \
--cpus-per-task 2 \
--mem 16G \
--module gcc/12 \
--module openmpi/4.1 \
-- \
./simulate --config config.json
# Write to a file and also emit structured JSON
python3 skills/hpc-deployment/slurm-job-script-generator/scripts/slurm_script_generator.py \
--job-name phasefield \
--time 00:10:00 \
--nodes 1 \
--ntasks 16 \
--cpus-per-task 1 \
--out job.sbatch \
--json \
-- \
/bin/echo hello
Conversational Workflow Example
User: I need an sbatch script for my MPI simulation. I want 2 nodes, 64 ranks per node, 2 OpenMP threads per rank, and 2 hours.
Agent workflow:
- Confirm partition/account and whether GPUs are needed.
- Generate a hybrid job script:
python3 scripts/slurm_script_generator.py --job-name run --time 02:00:00 --nodes 2 --ntasks-per-node 64 --cpus-per-task 2 -- ./simulate - Explain the mapping:
- Total ranks = 128
- Threads per rank = 2 (
OMP_NUM_THREADS=2)
- If the user provides node core counts, sanity-check oversubscription using
--cores-per-node.
Error Handling
| Error | Cause | Resolution |
|---|---|---|
time must be HH:MM:SS or D-HH:MM:SS | Bad walltime format | Use 00:30:00 or 1-00:00:00 |
nodes must be positive | Non-positive nodes | Provide --nodes >= 1 |
Provide either --mem or --mem-per-cpu, not both | Conflicting memory directives | Choose one memory style |
Provide a run command after -- | Missing launch command | Add -- ./simulate ... |
--partition must match /^[A-Za-z0-9]... | Partition/account/qos/constraint/reservation contains spaces or shell metacharacters | Use a plain identifier |
module must match /^[A-Za-z0-9]... | Module name contains shell metacharacters | Use e.g. gcc/12, openmpi/4.1 |
nodes must be <= 100000 (got ...) | Integer request exceeds the sanity upper bound | Re-check the requested value |
Verification checklist
- Confirmed the generated
results.scriptplaces every#SBATCHdirective immediately after the shebang and beforeset -euo pipefail(open the script and check the first real command line) — a directive after the first command is silently ignored by SLURM. - Inspected
results.warningsand confirmed it is empty, or recorded each warning (CPU oversubscription, non-integer task-to-GPU ratio, double-launcher) with a deliberate justification for ignoring it. - Recorded
results.derived.cpus_total_requested(=ntasks * cpus-per-task) and, when--cores-per-nodewas supplied, confirmedcpus_per_node_requested <= cores_per_nodeso the node is not oversubscribed. - For hybrid runs, verified the script's
export OMP_NUM_THREADSvalue equalsresults.derivedcpus_per_task(the generator sets them equal — confirm that matches the intended threads-per-rank). - For GPU jobs, recorded
results.derived.total_gpusandranks_per_gpuand confirmedranks_per_gpuis the intended integer (or documented intentional sharing such as MPS). - Verified
results.run_lineis not double-wrapped: if the run command already starts withsrun/mpirun/mpiexec/orterun/aprun/jsrun, confirmed--launcher nonewas used (or the auto-detect warning fired) so SLURM does not launch N independent copies. - Cross-checked the partition, account, QoS, memory style (
--memvs--mem-per-cpu), and GPU directive against the actual cluster's documented policy — the generator only validates internal consistency, never site policy.
Common pitfalls & rationalizations
| Tempting shortcut | Why it's wrong / what to do |
|---|---|
| "It generated a script with no errors, so the resources are correct." | The generator only checks internal consistency — it never queries the cluster. Validate partition/account/QoS/memory style and GPU directives against your site's actual docs before submitting. |
"I'll keep the srun/mpirun already in my run command and let the generator wrap it." | Wrapping srun around mpirun launches N independent mpirun processes (each its own MPI world); srun around srun is malformed. Pass --launcher none, and confirm the auto-detect warning fired in results.warnings. |
| "I requested the nodes I want, so the job will use them all." | If any #SBATCH directive slips below the first command it is silently dropped and the job falls back to cluster defaults. Re-read the generated script and confirm all directives precede set -euo pipefail. |
| "ntasks doesn't divide the GPU count, but it ran, so it's fine." | A non-integer ranks_per_gpu means ranks map unevenly to devices (idle/oversubscribed GPUs). The generator emits a task-to-GPU warning — fix ntasks/GPUs or explicitly document MPS sharing. |
"I set high ntasks-per-node because more ranks is faster." | Without --cores-per-node the generator can't catch oversubscription, and ntasks-per-node*cpus-per-task exceeding physical cores degrades performance. Pass --cores-per-node and check cpus_per_node_requested. |
"I'll set both --mem and --mem-per-cpu to be safe." | These are mutually exclusive; the generator rejects supplying both. Pick the one your cluster's policy enforces. |
| "OMP_NUM_THREADS doesn't matter for an MPI-only code." | The generator always exports OMP_NUM_THREADS=cpus-per-task; for MPI-only runs keep --cpus-per-task=1 so threaded libraries don't silently oversubscribe cores. |
Security
Input Validation
--timeis validated against strictHH:MM:SSorD-HH:MM:SSformat via regex (minutes/seconds in[00,59])--nodes,--ntasks,--ntasks-per-node,--cpus-per-task,--gpus-per-node,--cores-per-nodeare validated as positive integers with generous upper bounds (e.g. nodes ≤ 100000, ntasks ≤ 10000000, cpus-per-task ≤ 4096, gpus-per-node ≤ 64); the derived totalntasks = nodes * ntasks-per-nodeis also bounds-checked--memand--mem-per-cpuare validated against SLURM's accepted format (^[0-9]+([KMGT])?$); providing both simultaneously is rejected--job-nameis validated against^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$(no spaces or shell metacharacters)--partition,--account,--qos,--constraint,--reservation, and--gpu-typeare validated against a safe-character allowlist^[A-Za-z0-9][A-Za-z0-9._:,+-]{0,127}$before being emitted into#SBATCHdirectives--modulevalues are validated against^[A-Za-z0-9][A-Za-z0-9._/+-]{0,127}$to prevent shell injection (no;,|,&, backticks,$, or whitespace)--envkeys must be valid shell identifiers (^[A-Za-z_][A-Za-z0-9_]*$); values are shell-quoted in the generatedexportlines--srun-extrais tokenized withshlex.splitand each token is re-quoted withshlex.quote, so it cannot inject shell syntax (;,|,&,$, ...) into the run line- Invalid input causes the CLI to print a message to stderr and exit with code
2
File Access
- The script reads no external files; all inputs are provided via CLI arguments
--outwrites the generated sbatch script to a single specified file path- The generated script is a plain-text shell script with
#SBATCHdirectives; it contains no dynamically generated code
Tool Restrictions
- Read: Used to inspect script source, references, and existing job scripts
- Bash: Used to execute
slurm_script_generator.pywith explicit argument lists; the generated script itself is NOT executed by the agent - Write: Used to save the generated
.sbatchfile; writes are scoped to the user's working directory - Grep/Glob: Used to locate existing scripts, configs, and cluster documentation
Safety Measures
- No
eval(),exec(), or dynamic code generation - All subprocess calls use explicit argument lists (no
shell=True) - The run command (after
--) is shell-quoted token-by-token into the generated script but is never executed by the skill itself - Module names,
--srun-extratokens, and identifier-style fields are sanitized/quoted to prevent injection intomodule load, thesruninvocation, or#SBATCHdirectives - Generated scripts place all
#SBATCHdirectives immediately after the shebang (before any executable command, so SLURM does not stop parsing them) and useset -euo pipefailfor safe shell execution on the cluster
Limitations
- Does not query cluster hardware or site policies; it can only validate internal consistency.
- SLURM installations vary (GPU directives, QoS rules, partitions). Adjust directives for your site.
References
references/slurm_directives.md- Common#SBATCHdirectives and mapping tips
Version History
- v1.2.2 (2026-06-24): Added "Verification checklist" and "Common pitfalls & rationalizations" sections covering directive ordering, oversubscription, task-to-GPU mapping, launcher double-wrapping, and the generator's internal-consistency-only scope.
- v1.2.0 (2026-06-23): Fixed critical directive-ordering bug (all
#SBATCHlines now precedeset -euo pipefail), avoided double-launcher wrapping when the run command already starts withsrun/mpirun, added GPU task-to-GPU ratio warning and layout guidance, hardened input validation (integer upper bounds, partition/account/qos/constraint/reservation/gpu-type allowlists, module sanitization,--srun-extraquoting), escaped%jin--help, and corrected the Security and output documentation. - v1.1.0 (2026-03-26): Optimized description for discovery, added eval suite, security review, standardized metadata, and CHANGELOG.
- v1.0.0 (2026-02-25): Initial SLURM job script generator
示例提示词
帮我生成一份请求8个GPU节点的SLURM提交脚本并检查资源冲突。
所属插件
安装该插件会一并获得同领域的 23 个 Skill / MCP。
同插件的其他科研 Skill
- 制造解法验证与基准测试规划Plans verification and validation campaigns using manufactured solutions, canonical benchmarks. Use when an agent must prove a solver is correct before trusting results.
- 数值解空间时间收敛性分析Performs spatial/temporal convergence analysis for solution verification: observed order, Richardson extrapolation. Use when checking that a simulation result is grid/timestep independent.
- PDE数值微分格式选择Selects and applies numerical differentiation schemes for PDE/ODE discretization: finite-difference stencils. Use when choosing a spatial discretization scheme.
- 仿真结果FAIR归档打包Creates FAIR-minded reproducibility bundles for simulations: file inventories, hashes, units, engine versions. Use before publishing or archiving a simulation dataset.
- HPC作业运行诊断Diagnoses HPC runtime and scheduler problems for materials simulations: MPI/OpenMP/GPU layout, modules, scratch paths, walltime. Use when a cluster job fails, hangs, or underperforms.
- 线性方程组求解器选型Selects and configures linear solvers for Ax=b systems: direct (LU, Cholesky) versus iterative (CG, GMRES, BiCGSTAB) methods, sparsity. Use when choosing a linear solver for a simulation.
- 分子动力学分析方案规划Plans molecular dynamics post-processing for materials simulations: RDF, MSD/diffusion, VACF/VDOS, coordination numbers. Use when deciding which MD analysis to run and in what order.
- 数值模拟网格生成规划Plans and evaluates mesh generation for numerical simulations: grid resolution from physics scales, aspect ratio/skewness checks. Use when designing or auditing a simulation mesh.
- 非线性方程组求解器选型Selects and configures nonlinear solvers for root-finding, optimization, and least-squares problems: Newton, quasi-Newton, Broyden, Anderson acceleration. Use when choosing a nonlinear solver.
- 时间积分方法选择Selects and configures time-integration methods for ODE/PDE simulations: explicit Runge-Kutta, BDF, Rosenbrock. Use when choosing a time-stepping scheme for a solver.
- 偏微分方程数值稳定性分析Analyzes numerical stability for time-dependent PDE simulations: CFL/Fourier criteria, von Neumann analysis. Use when a simulation blows up or to check a scheme’s stability limits.
- 材料科学本体浏览查询Parses, navigates, and queries materials science ontology structures: class hierarchies, property domain/range lookup. Use when exploring an unfamiliar materials ontology.
- 材料术语本体映射Maps materials science terms, crystal structures, and sample descriptions to standardized ontology classes with confidence scores. Use when annotating data for ontology interoperability.
- 本体标注一致性校验Validates material sample annotations against ontology constraints: class/property existence, domain/range consistency. Use before publishing ontology-annotated materials data.
- 仿真参数优化与敏感性分析Explores and optimizes simulation parameters via design of experiments, sensitivity analysis, and optimizer selection: Latin Hypercube, quasi-random. Use when calibrating simulation parameters.
- 仿真计算性能剖析Identifies computational bottlenecks, parallel scaling, and memory requirements for materials simulations: parses timing logs for dominant phases. Use when a simulation is slow or scales poorly.
- 仿真输出数据后处理Extracts, analyzes, and summarizes simulation output data: spatial fields at timesteps, time-series trends, steady-state detection. Use when turning raw simulation output into summary statistics.
- 多代码仿真故障分诊Provides first-response triage for cross-code LAMMPS/VASP/QE/MOOSE simulation failures: classifies nonconvergence, NaN/Inf. Use when a simulation crashes and the cause is unclear.
- 多任务仿真批量编排Orchestrates multi-simulation campaigns: generates parameter sweeps (grid, linspace, Latin Hypercube), tracks batch job status. Use when running and managing many related simulation jobs.
- 仿真三阶段有效性校验Validates simulations across three stages: pre-flight config checks, runtime log monitoring for NaN/Inf and residual growth. Use to catch simulation errors before, during, and after a run.
- 瞬态仿真时间步策略Plans and controls time-step policies for transient simulations: CFL and physics-based stability limits, adaptive stepping. Use when setting up a time-stepping strategy for a solver.
- 计算材料工作流引擎选型Maps computational materials tasks onto workflow engines (atomate2, jobflow, AiiDA, pyiron) or a one-off script. Use when deciding how to structure a reproducible campaign or DAG.
常见问题
SLURM作业脚本生成能做什么?
Generates correct SLURM sbatch job scripts and sanity-checks HPC resource requests: nodes, MPI/OpenMP layout, memory, GPUs, walltime. Use when writing or debugging a SLURM submission script。
如何安装SLURM作业脚本生成?
在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「SLURM作业脚本生成」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。
SLURM作业脚本生成需要哪些权限?
该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。
SLURM作业脚本生成经过官方审核吗?
是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。