incar-performance

name	incar-performance
description	为 VASP INCAR 做性能调优与并行参数设置。当用户提到性能优化、并行策略、KPAR、NCORE、NPAR、CPU/GPU 资源映射、单卡/多卡、工作站或节点硬件，并希望根据设备调整 INCAR 时触发。只修改性能相关 INCAR 项，真正运行仍交给 run-vasp。
version	1.0.0

VASP 性能调优 Skill

这个 skill 的目标不是启动 VASP，而是在真正运行前根据用户的硬件资源，安全地调整 INCAR 中与性能相关的参数，避免 agent 凭印象乱写 KPAR、NCORE、NPAR。

何时必须使用

出现下列任一情形时，必须加载本 skill：

• 用户要求“优化性能”“并行测试”“调快一点”“根据机器改 INCAR”
• 用户明确提到 KPAR、NCORE、NPAR、NSIM、GPU 张数、CPU 核数
• 用户要求针对 CPU-only、单 GPU、多 GPU 或多节点场景分别给推荐设置
• 上游 skill 在正式运行前，需要根据计算设备改写 INCAR

本 skill 负责改写输入参数与解释策略，真正执行 VASP 仍应交给 run-vasp。

硬性流程

1. 必须先问设备

在修改 INCAR 之前，必须先确认用户实际使用的设备。若对话里没有明确说明，必须用纯文本向用户询问，并等待回复。

至少确认以下信息中的核心部分：

• 是 CPU-only，还是 GPU 加速
• 若是 GPU：使用几张 GPU
• 若是 CPU：每个任务打算用多少 CPU 核
• 是否是单节点，还是多节点

若用户已经在上文给出了这些信息，可直接进入下一步，不要重复追问。

2. 只改性能相关项

本 skill 只负责以下类型参数：

• KPAR
• NCORE
• NPAR（仅在明确需要时）
• NSIM（仅在明确需要时）
• 极少数与性能强相关但不改物理结果的辅助项

不要借性能优化之名，随意改变会影响物理可比性的核心参数，例如：

• ENCUT
• KSPACING
• ISMEAR
• SIGMA
• AEXX
• HFSCREEN

除非用户明确要求做 benchmark 或快速试算，并且你在回复中明确说明这是“性能/测试口径”而非生产口径。

3. 优先顺序

按以下顺序决定并行参数：

1. 先判断是 CPU-only 还是 GPU
2. 再判断是单任务还是多任务并发
3. 再根据设备数决定 KPAR
4. 最后才考虑 NCORE / NPAR

4. 修改后必须说明

每次改完 INCAR 后，必须向用户简要说明：

• 识别到的硬件场景
• 你改了哪些并行参数
• 为什么这么改
• 哪些参数你刻意没有改

推荐规则

详细映射表见 references/parallel_settings.md。实际执行时按下列简明规则优先判断。

A. CPU-only 单节点

• 优先考虑写 NCORE
• 通常不主动写 KPAR，除非用户明确要按 k 点并行
• NCORE 建议取每个 NUMA 域或每个 socket 内较自然的核数组块，例如 4、8、16
• 避免同时胡乱写 NCORE 和 NPAR

经验规则：

• <= 8 核：可不写 NCORE，或写 NCORE = 2/4
• 16–32 核：常从 NCORE = 4/8 试起
• >= 48 核：常从 NCORE = 8/12/16 试起

若用户只是要一个稳妥默认值，优先推荐：

• 中小型 CPU 作业：NCORE = 4
• 较大单节点 CPU 作业：NCORE = 8

B. 单 GPU

• 通常优先写 KPAR = 1
• 默认不写 NCORE
• 避免保留旧的 CPU 并行参数污染 GPU 任务

如果 INCAR 里已有旧的 NCORE / NPAR，且当前用户明确要 GPU 运行，通常应删除这些项，除非用户要求保留做对照。

C. 多 GPU 单任务

• KPAR 优先与 GPU 数对齐：1/2/4/8 ...
• 通常令 KPAR ≈ GPU 数
• 默认不写 NCORE

但必须注意：

• KPAR 不应明显大于可并行的 k 点组数
• 若体系的不可约 k 点很少，过大的 KPAR 可能没有收益
• 对 HSE、杂化泛函、k 点较多的静态任务，多 GPU + KPAR 往往尤其有效

D. 多任务并发占多张 GPU

如果用户实际上是“多个目录分别各占 1 张 GPU”而不是“一个任务同时占 8 张 GPU”，那就不应该把单个 INCAR 改成 KPAR = 8。

此时应明确区分：

• 单任务多 GPU：可以考虑 KPAR = GPU 数
• 多任务单 GPU 并发：每个任务通常仍是 KPAR = 1

E. 多节点 CPU / GPU

多节点场景优先由 run-vasp 处理作业脚本和 mpirun/调度器资源映射。

本 skill 对多节点 INCAR 的原则是：

• 不因为节点数增加，就随意增大 KPAR
• 不在信息不足时拍脑袋设置 NCORE
• 若用户只说明“多节点”但没给每节点核数/GPU 数，应先继续追问

明确禁忌

• 不要在 GPU 场景里沿用旧的 NCORE 作为默认配置
• 不要无依据地同时写 KPAR、NCORE、NPAR
• 不要把“多任务并发”误判成“单任务多卡”
• 不要因为机器很大就默认把 KPAR 设得很大
• 不要把性能调参和物理参数收敛混为一谈

与其它 Skill 的配合

• 需要真正启动 VASP 时，转交 run-vasp
• workflow-electronic-structure、workflow-convergence、workflow-relax、workflow-eos-lattice-constant 等 skill 在用户明确要求按硬件优化 INCAR 时，应先使用本 skill，再进入运行阶段
• 若用户只是问“怎么设置更快”，而没有要求开跑，可以只修改/建议 INCAR，不调用 run-vasp

最终产出要求

完成本 skill 后，你应至少做到以下之一：

• 直接改写工作区中的 INCAR
• 或明确给出应如何改写 INCAR 的补丁方案

并在回复中包含：

• 已识别硬件
• 采用的并行策略
• 修改后的关键参数

若信息不足，先问设备问题，停止生成，等待用户回复。