CANN/ops-math Polar算子测试指南

Polar 算子测试步骤指导文档（ops-math 仓内构建）

【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math

本文档指导验收人员在昇腾 NPU 环境复现全部测试。本地无 NPU 无法运行，须在 Atlas A2/A3（910B4）环境（ModelArts notebook / Developer Space）操作。

约定：$OPSMATH= ops-math 仓根目录（含本算子experimental/math/polar/）；$POLAR=$OPSMATH/experimental/math/polar。

0. 环境前置（所有测试共用）

source /home/ma-user/Ascend/cann-8.5.0/set_env.sh # 路径以实际环境为准 export PATH=/home/ma-user/gcc/bin:$PATH # 如已配可跳过 export LD_LIBRARY_PATH=/home/ma-user/gcc/lib64:$LD_LIBRARY_PATH

1. 在 ops-math 仓内构建并部署 Polar 算子

本算子已按 ops-mathexperimental/math约定集成，随仓build.sh构建：

本算子在op_host/polar_def.cpp中通过AICore().AddConfig("ascend910b")与AddConfig("ascend910_93")同时注册 Atlas A2 / A3 两套 SoC 配置，按--soc选择目标二进制：

cd $OPSMATH # Atlas A2 训练系列产品 (ascend910b) bash build.sh --pkg --soc=ascend910b --ops=polar --experimental --vendor_name=customize -j16 -O3 # Atlas A3 训练系列产品 (ascend910_93)，二选一即可，亦可分别 build 各自的 .run # bash build.sh --pkg --soc=ascend910_93 --ops=polar --experimental --vendor_name=customize -j16 -O3 ./build_out/*.run --quiet # 安装到 $ASCEND_HOME_PATH/opp/vendors/customize_math/

使部署算子生效（关键，否则解析不到自定义实现）：

source $ASCEND_HOME_PATH/opp/vendors/customize_math/bin/set_env.bash 2>/dev/null || true export LD_LIBRARY_PATH=$ASCEND_HOME_PATH/opp/vendors/customize_math/op_api/lib:$LD_LIBRARY_PATH

注：ops-math build 强制 vendor 名为customize_math（与--vendor_name无关）；aclnn 接口（aclnn_polar.h+aclnnPolar/aclnnPolarGetWorkspaceSize符号）由 build 从 OpDef 自动生成并装入该 vendor 的op_api/。 ✅ 已在 Atlas A2（910B4）NPU 实测（2026-05-19）：本步构建通过 + §2 官方 AscendOpTest6/6 全 PASS，与原 msopgen 产物精度一致、重构零回归。Atlas A3（ascend910_93）通过同一份 OpDef + Kernel 同源构建得到对应.run包；kernel 与 host tiling 不含任何平台分支（grep 校验过），构建产物结构与 A2 一致。

2. 官方 AscendOpTest 精度验收（任务权威精度判据，优先跑）

pip install ml_dtypes cd $POLAR/tests && git clone https://gitcode.com/HIT1920/AscendOpTest.git cd AscendOpTest # 修正用例 expect_func 绝对路径 → 指向本仓 polar_golden.py（保留 :polar 函数名后缀） sed -i "s#\"expect_func\": \".*polar_golden.py:polar\"#\"expect_func\": \"$POLAR/tests/aot/polar_golden.py:polar\"#g" \ $POLAR/tests/aot/polar_cases.json python run_test.py \ -i $POLAR/tests/Polar.json \ -c $POLAR/tests/aot/polar_cases.json \ --op-type custom --op-path $ASCEND_HOME_PATH/opp/vendors/customize_math/op_api --build

结果在result.csv。6 用例：Test_same_small、Test_same_16M、Test_bcast_lowhigh、Test_bcast_scalar、Test_bcast_2way、Test_highdim_unalign，预期全 PASS（含 16M）。

精度判据：complex64 在 AscendOpTestaccuracy_config无内置默认 → 每个output_desc显式"err_threshold":[0.0001,0.0001]；compare_complex= 实/虚部各自纯绝对误差 ≤ 1e-4（无相对回退），错误元素数 > size×1e-4 即失败。

性能（msprof，复用已 build 工程，不再加 --build）：

python run_test.py -i $POLAR/tests/Polar.json -c $POLAR/tests/aot/polar_cases.json \ --op-type custom --op-path $ASCEND_HOME_PATH/opp/vendors/customize_math/op_api --msprof

聚合每用例op_summary*.csv的 Task Duration = 每调用设备时（与自测报告口径一致）。

3. pybind 测试框架（16 case：基础 8 + 泛化交叉 8）

依赖torch_npu，算子已按 §1 部署。

cd $POLAR/tests/pybind bash run.sh 1 # 同 shape 基础 bash run.sh 2 # 广播 低→高（新增功能主战场） # case 列表见本目录 README.md / test_op.py 的 case_data

输出xxx verify result pass!+time_base=... time_use=...。verify_result与官方compare_complex逐行等价（实/虚部纯绝对误差 1e-4）。case9–16 = 泛化交叉（8D 满秩 / 5D 中间轴广播 / 双向多轴广播 / 标量×高维 / 负 abs / 大角度归约 / 非 32B 对齐+广播 / 大向量×标量）。

4. l0 参考实现性能基线对比

tests/pybind_baseline/与 pybind 同构，其common/pytorch_npu_helper.hpp强制GetOpApiFuncAddr只解析系统libopapi.so（l0 参考），不触碰任何共享 vendor 目录。

cd $POLAR/tests/pybind_baseline bash run.sh 5 # 同 case 在 l0 参考上的耗时 = 性能基线

与 §3/§2 本算子耗时对比得加速比（核心验收：所有核参与场景 ≥ 基线 95%；本算子 16M 达 178%）。

5. standalone aclnn 两段式调用测试

examples/test_aclnn_polar.cpp（不依赖 torch，5 用例 warmup+计时+CPU 校验），_ref调系统 l0。CANN 8.5 编译：

OPP=$ASCEND_HOME_PATH/opp/vendors/customize_math ACLINC=$ASCEND_HOME_PATH/aarch64-linux/include ASCLIB=$ASCEND_HOME_PATH/aarch64-linux/lib64 # 必须 lib64，勿用 devlib g++ -O2 -std=c++17 -I$ACLINC -I$OPP/op_api/include -L$ASCLIB -L$OPP/op_api/lib \ $POLAR/examples/test_aclnn_polar.cpp -o /tmp/test_aclnn_polar \ -lascendcl -lnnopbase -lcust_opapi LD_LIBRARY_PATH=$OPP/op_api/lib:$ASCLIB:$LD_LIBRARY_PATH /tmp/test_aclnn_polar # 基线版：源换 test_aclnn_polar_ref.cpp，库 -lcust_opapi 换 -lopapi

standalone 自带 verify 仅作冒烟；精度以 §2 官方 AscendOpTest 为准。

附：测试与交付项对应

【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math