| name | shmem-ops-testcase-gen |
| description | 为基于 SHMEM 的算子生成正确性测试计划、case matrix、golden/checker 和测试脚本。关键词:基于SHMEM测试用例、case matrix、golden、checker、gen_data、check_result。 |
SHMEM 算子测试用例生成
Skill类型:文档与脚本生成型(读取设计文档,输出测试计划和验证脚本)
中文写作要求:测试计划和 case matrix 文档必须使用中文撰写。仅 Case ID、代码片段、API 名称等技术术语保留英文原文。
将 design.md 中的 correctness contract 和 invariants 转化为可执行的测试计划、数据生成脚本和精度验证脚本。测试计划是实现约束,必须在代码生成前完成。
必读资料
输入
design.md 的 correctness 字段:oracle、rtol/atol、invariants、case_matrix
design.md 的 interface 字段:inputs/outputs/dtype/shape
design.md 的 semantics 字段:local_compute、communication、finalize
工作流
步骤 1 提取 correctness contract
步骤 2 生成 case matrix
步骤 3 生成数据生成脚本 (gen_data.py)
步骤 4 生成精度验证脚本 (check_result.py)
步骤 5 生成运行脚本 (`scripts/run.sh`)
步骤 1:提取 correctness contract
从 design.md 中提取:
- oracle 方案(rank pattern / CPU numpy / PyTorch / file-based)
- tolerance(rtol/atol,按 dtype 区分)
- invariants 列表
- case matrix 规模要求
步骤 2:生成 case matrix
必须按 references/testcase-scale-standard.md 的规模分档生成,覆盖 XS/S/M/L 四档 + 边界 + 压力,总 case 数 ≥ 20。类别要求详见 references/correctness.md §3。
步骤 3:生成 gen_data.py
职责:
- 固定随机种子(
np.random.seed(42)),确保可复现
- 为每个 PE 生成独立输入文件(
input_pe{rank}.bin)
- 计算 golden 输出(使用高精度 float32)
- 保存 golden 文件(
golden_pe{rank}.bin 或 golden.bin)
- 保存配置文件(shape、dtype、PE 数等)
Golden 构造方法:
- 通信算子:rank pattern — 直接按通信语义构造期望输出;可选 CPU numpy/PyTorch 参考实现作兜底
- 通算融合算子:PyTorch / CPU numpy 参考实现 — 模拟 local compute → communication → finalize 全流程(见 correctness.md §4.3)
步骤 4:生成 check_result.py
职责:
- 读取算子输出和 golden 文件
- 按
meta.op_kind 和 dtype 选择 tolerance(不能一律使用 1e-5);op_kind → OpTypes 映射见 precision-standard.md §5.1
- 每个 PE 计算并打印 MaxAE、MaxRE、MeanRE 和 tolerance 阈值
- 打印详细 mismatch(PE、index、actual、expected、error)
- 返回明确退出码(0=通过,非0=失败)
Tolerance 选择规则详见 references/precision-standard.md。scripts/run.sh 调用 check_result.py 时必须显式传 --rtol 和 --atol,不依赖脚本内默认值。
步骤 5:生成 scripts/run.sh
按 test-structure-template.md §4 生成算子内 scripts/run.sh。
交付入口(custom-ops 默认):skill/README MUST 以 custom-ops-entrypoints.md §2 为首选运行入口,算子内 scripts/run.sh 为被转发实现。build 失败提示 MUST 为同文件 §1 编译。
多 PE 启动脚本,每个 PE 一个独立进程。
环境设置 MUST 内联 env-setup.snippet.md 中的 setup_shmem_runtime_env,或在模板中等价内联:先激活 SHMEM install 环境脚本,再追加 build/lib 和 ${ASCEND_HOME_PATH}/lib64。禁止只手动设 LD_LIBRARY_PATH=build/lib。
输出产物
op_name/
├── scripts/
│ ├── gen_data.py
│ ├── check_result.py
│ ├── `scripts/run.sh`
│ └── run_case_matrix.py
└── data/ (gen_data.py 生成)
├── input_pe0.bin
├── input_pe1.bin
├── golden.bin
└── config.json
case matrix 执行报告输出到 docs/case_matrix_report.md。
MUST检查
反模式(NEVER DO THESE)
- ❌ golden 逻辑放在 main.cpp 中
- ❌ 精度验证放在 main.cpp 中
- ❌ 只有 smoke case 没有 medium scale
- ❌ 只覆盖单一规模档次(必须覆盖 XS/S/M/L 四档)
- ❌ 总 case 数不足 20
- ❌ golden 用低精度计算导致误差累积
- ❌ 测试脚本依赖未声明的环境变量
- ❌
scripts/run.sh 只设 LD_LIBRARY_PATH=build/lib,不 source ${SHMEM_REPO}/install/set_env.sh`
- ❌
scripts/run.sh 写死 IPPORT=tcp://127.0.0.1:27010 等全局默认端口(与 Torch 测试或其它 run 并行时 shmem init 失败)
- ❌
result_compare.py / checker 的 dtype 与 golden 生成 dtype 不一致(如 int8 数据用 float16 读取)
- ❌ transport/纯搬运算子使用 relaxed tolerance(应为 bitwise exact)
- ❌ check_result.py 只打印 PASS/FAIL 不输出 MaxAE/MaxRE/MeanRE