CANN ops-math Coordinates1DTo2D 算子实战基于 shape 的 1D 坐标转 2D 行列索引实现与调用指南【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-mathCoordinates1DTo2D 是 CANN ops-math 数学算子库conversion 模块中提供的数据坐标变换类算子其核心功能是将一维线性坐标索引转换为二维行、列索引并根据 shape 信息输出对应的列数。本文以该算子的官方说明文档为主体结合仓库中的算子 IR 定义、Shape 推导实现、AICPU 内核实现与单元测试系统讲解其功能原理、参数约束、计算规则、图模式调用方式与验证方法帮助读者在 Ascend NPU 上正确使用与二次开发该算子。产品支持情况根据算子说明文档Coordinates1DTo2D 算子支持以下昇腾硬件产品产品是否支持Ascend 950PR / Ascend 950DT√Atlas A3 训练系列产品 / Atlas A3 推理系列产品√Atlas A2 训练系列产品 / Atlas A2 推理系列产品√Atlas 200I/500 A2 推理产品√Atlas 推理系列产品√Atlas 训练系列产品√功能说明算子功能将 1D 坐标转换为 2D 坐标根据 shape 信息计算行列索引。具体而言该算子接收一个一维线性坐标索引x以及一个包含 4 个元素的形状向量shape (N, D, H, W)输出三个标量结果行索引、列索引以及列数。其数学含义可理解为将 4 维张量按行优先row-major扁平化后的线性偏移量反向拆解为某一行上的列位置。从内核实现的源码可以直接看到其核心计算逻辑T val *x_data; T col_num shape_data[3]; *row_data val / col_num; *col_data val % col_num; *n_data col_num;即output_row x / W整除得到行索引output_col x % W取余得到列索引output_n W输出列数即 shape 的 W 维度值。其中W shape[3]。以shape (2, 2, 2, 5)为例线性坐标x 25将转换为row 25 / 5 5、col 25 % 5 0、n 5这一结果与内核单元测试中的TestCoordinates1DTo2D_basic_int64用例完全一致。该算子在算子 IR 定义中声明的官方语义为 Converts 1D coordinate to 2D coordinate based on shape information属于数据变换Data Transformation类算子。参数说明下表完整列出了 Coordinates1DTo2D 算子的全部输入输出参数源自官方参数说明并与算子 IR 定义中的REG_OP声明保持一致参数名输入/输出/属性描述数据类型数据格式x输入1D 坐标索引值。INT32、INT64、UINT64NDshape输入形状信息包含 4 个元素 (N, D, H, W)。INT32、INT64、UINT64NDoutput_row输出输出的行索引。INT32、INT64、UINT64NDoutput_col输出输出的列索引。INT32、INT64、UINT64NDoutput_n输出输出的列数W 维度值。INT32、INT64、UINT64ND从算子注册信息看x与shape两个输入均只支持DT_INT32 / DT_INT64 / DT_UINT64三种整型类型三个输出row、col、n的类型集合与输入完全一致见 coordinates_1d_to_2d_proto.h 与 coordinates_1d_to_2d_aicpu_def.cpp。数据格式均为 ND普通稠密格式算子本身通过OP_INFO_FORMAT_AGNOSTIC声明为格式无关算子。约束说明使用 Coordinates1DTo2D 算子时必须满足以下约束来自官方约束说明input[shape] 元素个数必须为 4即 shape 必须恰好是(N, D, H, W)四个维度。内核中通过KERNEL_CHECK_FALSE((shape-NumElements() kShapeNum), ...)显式校验kShapeNum 4单测用例TestCoordinates1DTo2D_INVALID_SHAPE_SIZE使用元素数为 3 的 shape 验证了该非法场景会返回KERNEL_STATUS_INNER_ERROR。input[x] 与 input[shape] 数据类型必须一致内核中通过KERNEL_CHECK_FALSE((x_dt shape-GetDataType()), ...)校验两个输入的数据类型一致否则返回KERNEL_STATUS_INNER_ERROR单测用例TestCoordinates1DTo2D_TYPE_MISMATCH以x为 INT32、shape为 INT64 的混搭方式验证了该错误分支。shape[3]W 维度不能为 0因为计算依赖x / W与x % WW 为 0 会产生除零错误。内核在取数据后首先执行KERNEL_CHECK_FALSE((shape_data[3] ! 0), KERNEL_STATUS_PARAM_INVALID, ...)校验单测用例TestCoordinates1DTo2D_zero_col使用shape (1, 1, 1, 0)验证了该非法场景返回KERNEL_STATUS_PARAM_INVALID。实现原理与源码解析Shape/DataType 推导输出形状与类型继承自输入 x在构图阶段算子的输出 shape 与数据类型由 Host 侧的 Infershape 逻辑确定。见 coordinates_1d_to_2d_infershape.cpp其注册了三个推导函数Coordinates1DTo2DInferShape将输入x的 shape 原样复制给三个输出row、col、n*rowShape *xShape;等即输出 shape 与输入 x 的 shape 完全一致Coordinates1DTo2DInferDataType将输入x的数据类型原样设置为三个输出的数据类型Coordinates1DTo2DInferShapeRange将输入x的动态 shape 范围min/max同步复制给三个输出。Host 侧单元测试验证了这一点当x的 shape 为{100}时三个输出的期望 shape 均为{100}当x为 INT64 时三个输出也均为 INT64。因此可以推断在典型用法中x是一个形状为{1}或与输出一致的任意形状的标量张量而输出与其形状相同。AICPU 内核单元素坐标换算算子运行在 AICPUAI CPU上内核类Coordinates1DTo2DCpuKernel继承自CpuKernel声明见 coordinates_1d_to_2d_aicpu.h实现见 coordinates_1d_to_2d_aicpu.cpp。其执行流程为NormalCheck(ctx, kInputNum, kOutputNum)检查输入个数为 2、输出个数为 3依次取出x、shape与三个输出张量校验x与shape的数据类型一致、shape元素个数为 4按数据类型分发到模板函数Coordinates1DTo2DComputeT分别实例化int32_t、int64_t、uint64_t三种类型在模板函数中校验shape[3] ! 0后执行row x / W、col x % W、n W的换算并通过KERNEL_LOG_INFO打印输入输出日志便于排查。内核通过OPS_MATH_REGISTER_CPU_KERNELV2(kCoordinates1DTo2D, Coordinates1DTo2DCpuKernel)注册到算子内核库kCoordinates1DTo2D Coordinates1DTo2D。算子定义注册算子的 AICPU OpDef 注册见 coordinates_1d_to_2d_aicpu_def.cpp它声明了 2 个输入、3 个输出及其数据类型集合并通过ApplyMathAicpuDefaultCfg应用数学类 AICPU 算子默认配置同时通过OP_INFO_FORMAT_AGNOSTIC声明算子格式无关、OP_INFO_OPS_FLAG声明为开放算子OpenOps。算子的构建入口见 CMakeLists.txt其中add_all_modules_sources(OPTYPE coordinates_1d_to_2d ACLNNTYPE aclnn_exclude HOSTCPU TRUE)表明该算子作为 Host CPU 算子参与构建ACLNN 类型被显式排除即不提供独立的 AclNN 接口而通过 GE 图模式接入。调用说明图模式Coordinates1DTo2D 算子通过图模式接口调用先通过算子 IRGE IR构建计算图再交给 GE 图引擎编译执行。完整可运行样例位于 examples/test_geir_coordinates_1d_to_2d.cpp其调用方式与流程如下表与官方调用说明一致调用方式样例代码说明图模式接口test_geir_coordinates_1d_to_2d通过算子 IR 接口方式调用 Coordinates1DTo2D 算子。该样例覆盖了从 GE 初始化、构图、建会话到跑图的完整链路关键步骤拆解如下包含算子 IR 头文件#include ../op_graph/coordinates_1d_to_2d_proto.h该头文件基于REG_OP(Coordinates1DTo2D)宏自动生成 C 算子封装类op::Coordinates1DTo2D。初始化 GE调用ge::GEInitialize(global_options)其中global_options设置{ge.exec.deviceId, 0}指定 0 号设备与{ge.graphRunMode, 1}图运行模式。构造输入数据样例中x使用 shape 为{1}的张量数据值为5shape使用 shape 为{4}的张量数据值为{1, 1, 1, 10}。样例封装了GenTestData生成 x 数据与GenShapeData生成 shape 数据两个辅助函数并支持 INT32 / INT64 / UINT64 三种数据类型程序运行时可通过命令行参数int32、int64、uint64指定默认int64。构建计算图创建op::Data占位节点placeholder_x、placeholder_shape分别设置attr_index为 0 和 1并标记为kPlacementHost主机侧输入然后创建算子节点auto coordinates_1d_to_2d_op op::Coordinates1DTo2D(coordinates_1d_to_2d); coordinates_1d_to_2d_op.set_input_x(placeholder_x); coordinates_1d_to_2d_op.set_input_shape(placeholder_shape); coordinates_1d_to_2d_op.update_output_desc_row(output_row_desc); coordinates_1d_to_2d_op.update_output_desc_col(output_col_desc); coordinates_1d_to_2d_op.update_output_desc_n(output_n_desc);构图与运行graph.SetInputs(inputs).SetOutputs(outputs)设置图输入输出后创建ge::Session调用session-AddGraph(graph_id, graph, graph_options)将图加入会话graph_options中通过{ge.exec.exclude_engines, AiCore}指定排除 AiCore 引擎即强制走 AICPU 执行随后调用session-RunGraph(graph_id, input, output)执行图并获取输出。结果落盘与打印SaveInputOutput将输入输出张量分别写为tc_ge_irrun_test_npu_input_*.bin与tc_ge_irrun_test_npu_output_*.bin二进制文件并在终端打印输出前 10 个元素。资源释放delete session后调用ge::GEFinalize()完成 GE 收尾。对于样例默认输入x 5、shape {1, 1, 1, 10}期望输出为output_row 0、output_col 5、output_n 10——这一结果与内核单测TestCoordinates1DTo2D_basic_int32完全一致可作为跑通后的结果比对基准。单元测试验证该算子在仓库中提供了 Host 与 AICPU 两套单元测试可用于验证行为正确性内核测试tests/ut/op_kernel_aicpu/test_coordinates_1d_to_2d.cpp通过NodeDefBuilder构造算子节点并调用RUN_KERNEL执行覆盖以下场景三种数据类型的正常换算INT32x5, W10 → row0, col5, n10、INT64x25, W5 → row5, col0, n5、UINT64x15, W10 → row1, col5, n10非法场景x 与 shape 类型不一致期望KERNEL_STATUS_INNER_ERROR、shape 元素个数不为 4期望KERNEL_STATUS_INNER_ERROR、W0期望KERNEL_STATUS_PARAM_INVALID边界场景x 分别为 0、5、15 且 W4 时的行/列换算结果row/col 均在 [0, W) 区间内。Infershape 测试tests/ut/op_host/test_coordinates_1d_to_2d_infershape.cpp通过InfershapeContextPara构造推导上下文验证输出 shape 与输入 x 一致如 x 为{100}时三个输出均为{100}、输出数据类型跟随输入 x。总结Coordinates1DTo2D 是 CANN ops-math 中一个实现简洁、语义清晰的坐标变换算子它接收 1D 线性坐标x与四维形状(N, D, H, W)通过row x / W、col x % W、n W完成向 2D 行列索引的换算广泛适用于需要将扁平索引映射回多维张量位置的场景。使用时需严格遵守三项约束shape 元素个数为 4、x 与 shape 类型一致、W 不为 0并通过图模式接口基于算子 IR 完成调用。读者可结合本仓库中的算子 IR、Infershape、AICPU 内核与完整样例进一步深入其实现细节与二次开发方法。【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CANN ops-math Coordinates1DTo2D 算子实战：基于 shape 的 1D 坐标转 2D 行列索引实现与调用指南
CANN ops-math Coordinates1DTo2D 算子实战基于 shape 的 1D 坐标转 2D 行列索引实现与调用指南【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-mathCoordinates1DTo2D 是 CANN ops-math 数学算子库conversion 模块中提供的数据坐标变换类算子其核心功能是将一维线性坐标索引转换为二维行、列索引并根据 shape 信息输出对应的列数。本文以该算子的官方说明文档为主体结合仓库中的算子 IR 定义、Shape 推导实现、AICPU 内核实现与单元测试系统讲解其功能原理、参数约束、计算规则、图模式调用方式与验证方法帮助读者在 Ascend NPU 上正确使用与二次开发该算子。产品支持情况根据算子说明文档Coordinates1DTo2D 算子支持以下昇腾硬件产品产品是否支持Ascend 950PR / Ascend 950DT√Atlas A3 训练系列产品 / Atlas A3 推理系列产品√Atlas A2 训练系列产品 / Atlas A2 推理系列产品√Atlas 200I/500 A2 推理产品√Atlas 推理系列产品√Atlas 训练系列产品√功能说明算子功能将 1D 坐标转换为 2D 坐标根据 shape 信息计算行列索引。具体而言该算子接收一个一维线性坐标索引x以及一个包含 4 个元素的形状向量shape (N, D, H, W)输出三个标量结果行索引、列索引以及列数。其数学含义可理解为将 4 维张量按行优先row-major扁平化后的线性偏移量反向拆解为某一行上的列位置。从内核实现的源码可以直接看到其核心计算逻辑T val *x_data; T col_num shape_data[3]; *row_data val / col_num; *col_data val % col_num; *n_data col_num;即output_row x / W整除得到行索引output_col x % W取余得到列索引output_n W输出列数即 shape 的 W 维度值。其中W shape[3]。以shape (2, 2, 2, 5)为例线性坐标x 25将转换为row 25 / 5 5、col 25 % 5 0、n 5这一结果与内核单元测试中的TestCoordinates1DTo2D_basic_int64用例完全一致。该算子在算子 IR 定义中声明的官方语义为 Converts 1D coordinate to 2D coordinate based on shape information属于数据变换Data Transformation类算子。参数说明下表完整列出了 Coordinates1DTo2D 算子的全部输入输出参数源自官方参数说明并与算子 IR 定义中的REG_OP声明保持一致参数名输入/输出/属性描述数据类型数据格式x输入1D 坐标索引值。INT32、INT64、UINT64NDshape输入形状信息包含 4 个元素 (N, D, H, W)。INT32、INT64、UINT64NDoutput_row输出输出的行索引。INT32、INT64、UINT64NDoutput_col输出输出的列索引。INT32、INT64、UINT64NDoutput_n输出输出的列数W 维度值。INT32、INT64、UINT64ND从算子注册信息看x与shape两个输入均只支持DT_INT32 / DT_INT64 / DT_UINT64三种整型类型三个输出row、col、n的类型集合与输入完全一致见 coordinates_1d_to_2d_proto.h 与 coordinates_1d_to_2d_aicpu_def.cpp。数据格式均为 ND普通稠密格式算子本身通过OP_INFO_FORMAT_AGNOSTIC声明为格式无关算子。约束说明使用 Coordinates1DTo2D 算子时必须满足以下约束来自官方约束说明input[shape] 元素个数必须为 4即 shape 必须恰好是(N, D, H, W)四个维度。内核中通过KERNEL_CHECK_FALSE((shape-NumElements() kShapeNum), ...)显式校验kShapeNum 4单测用例TestCoordinates1DTo2D_INVALID_SHAPE_SIZE使用元素数为 3 的 shape 验证了该非法场景会返回KERNEL_STATUS_INNER_ERROR。input[x] 与 input[shape] 数据类型必须一致内核中通过KERNEL_CHECK_FALSE((x_dt shape-GetDataType()), ...)校验两个输入的数据类型一致否则返回KERNEL_STATUS_INNER_ERROR单测用例TestCoordinates1DTo2D_TYPE_MISMATCH以x为 INT32、shape为 INT64 的混搭方式验证了该错误分支。shape[3]W 维度不能为 0因为计算依赖x / W与x % WW 为 0 会产生除零错误。内核在取数据后首先执行KERNEL_CHECK_FALSE((shape_data[3] ! 0), KERNEL_STATUS_PARAM_INVALID, ...)校验单测用例TestCoordinates1DTo2D_zero_col使用shape (1, 1, 1, 0)验证了该非法场景返回KERNEL_STATUS_PARAM_INVALID。实现原理与源码解析Shape/DataType 推导输出形状与类型继承自输入 x在构图阶段算子的输出 shape 与数据类型由 Host 侧的 Infershape 逻辑确定。见 coordinates_1d_to_2d_infershape.cpp其注册了三个推导函数Coordinates1DTo2DInferShape将输入x的 shape 原样复制给三个输出row、col、n*rowShape *xShape;等即输出 shape 与输入 x 的 shape 完全一致Coordinates1DTo2DInferDataType将输入x的数据类型原样设置为三个输出的数据类型Coordinates1DTo2DInferShapeRange将输入x的动态 shape 范围min/max同步复制给三个输出。Host 侧单元测试验证了这一点当x的 shape 为{100}时三个输出的期望 shape 均为{100}当x为 INT64 时三个输出也均为 INT64。因此可以推断在典型用法中x是一个形状为{1}或与输出一致的任意形状的标量张量而输出与其形状相同。AICPU 内核单元素坐标换算算子运行在 AICPUAI CPU上内核类Coordinates1DTo2DCpuKernel继承自CpuKernel声明见 coordinates_1d_to_2d_aicpu.h实现见 coordinates_1d_to_2d_aicpu.cpp。其执行流程为NormalCheck(ctx, kInputNum, kOutputNum)检查输入个数为 2、输出个数为 3依次取出x、shape与三个输出张量校验x与shape的数据类型一致、shape元素个数为 4按数据类型分发到模板函数Coordinates1DTo2DComputeT分别实例化int32_t、int64_t、uint64_t三种类型在模板函数中校验shape[3] ! 0后执行row x / W、col x % W、n W的换算并通过KERNEL_LOG_INFO打印输入输出日志便于排查。内核通过OPS_MATH_REGISTER_CPU_KERNELV2(kCoordinates1DTo2D, Coordinates1DTo2DCpuKernel)注册到算子内核库kCoordinates1DTo2D Coordinates1DTo2D。算子定义注册算子的 AICPU OpDef 注册见 coordinates_1d_to_2d_aicpu_def.cpp它声明了 2 个输入、3 个输出及其数据类型集合并通过ApplyMathAicpuDefaultCfg应用数学类 AICPU 算子默认配置同时通过OP_INFO_FORMAT_AGNOSTIC声明算子格式无关、OP_INFO_OPS_FLAG声明为开放算子OpenOps。算子的构建入口见 CMakeLists.txt其中add_all_modules_sources(OPTYPE coordinates_1d_to_2d ACLNNTYPE aclnn_exclude HOSTCPU TRUE)表明该算子作为 Host CPU 算子参与构建ACLNN 类型被显式排除即不提供独立的 AclNN 接口而通过 GE 图模式接入。调用说明图模式Coordinates1DTo2D 算子通过图模式接口调用先通过算子 IRGE IR构建计算图再交给 GE 图引擎编译执行。完整可运行样例位于 examples/test_geir_coordinates_1d_to_2d.cpp其调用方式与流程如下表与官方调用说明一致调用方式样例代码说明图模式接口test_geir_coordinates_1d_to_2d通过算子 IR 接口方式调用 Coordinates1DTo2D 算子。该样例覆盖了从 GE 初始化、构图、建会话到跑图的完整链路关键步骤拆解如下包含算子 IR 头文件#include ../op_graph/coordinates_1d_to_2d_proto.h该头文件基于REG_OP(Coordinates1DTo2D)宏自动生成 C 算子封装类op::Coordinates1DTo2D。初始化 GE调用ge::GEInitialize(global_options)其中global_options设置{ge.exec.deviceId, 0}指定 0 号设备与{ge.graphRunMode, 1}图运行模式。构造输入数据样例中x使用 shape 为{1}的张量数据值为5shape使用 shape 为{4}的张量数据值为{1, 1, 1, 10}。样例封装了GenTestData生成 x 数据与GenShapeData生成 shape 数据两个辅助函数并支持 INT32 / INT64 / UINT64 三种数据类型程序运行时可通过命令行参数int32、int64、uint64指定默认int64。构建计算图创建op::Data占位节点placeholder_x、placeholder_shape分别设置attr_index为 0 和 1并标记为kPlacementHost主机侧输入然后创建算子节点auto coordinates_1d_to_2d_op op::Coordinates1DTo2D(coordinates_1d_to_2d); coordinates_1d_to_2d_op.set_input_x(placeholder_x); coordinates_1d_to_2d_op.set_input_shape(placeholder_shape); coordinates_1d_to_2d_op.update_output_desc_row(output_row_desc); coordinates_1d_to_2d_op.update_output_desc_col(output_col_desc); coordinates_1d_to_2d_op.update_output_desc_n(output_n_desc);构图与运行graph.SetInputs(inputs).SetOutputs(outputs)设置图输入输出后创建ge::Session调用session-AddGraph(graph_id, graph, graph_options)将图加入会话graph_options中通过{ge.exec.exclude_engines, AiCore}指定排除 AiCore 引擎即强制走 AICPU 执行随后调用session-RunGraph(graph_id, input, output)执行图并获取输出。结果落盘与打印SaveInputOutput将输入输出张量分别写为tc_ge_irrun_test_npu_input_*.bin与tc_ge_irrun_test_npu_output_*.bin二进制文件并在终端打印输出前 10 个元素。资源释放delete session后调用ge::GEFinalize()完成 GE 收尾。对于样例默认输入x 5、shape {1, 1, 1, 10}期望输出为output_row 0、output_col 5、output_n 10——这一结果与内核单测TestCoordinates1DTo2D_basic_int32完全一致可作为跑通后的结果比对基准。单元测试验证该算子在仓库中提供了 Host 与 AICPU 两套单元测试可用于验证行为正确性内核测试tests/ut/op_kernel_aicpu/test_coordinates_1d_to_2d.cpp通过NodeDefBuilder构造算子节点并调用RUN_KERNEL执行覆盖以下场景三种数据类型的正常换算INT32x5, W10 → row0, col5, n10、INT64x25, W5 → row5, col0, n5、UINT64x15, W10 → row1, col5, n10非法场景x 与 shape 类型不一致期望KERNEL_STATUS_INNER_ERROR、shape 元素个数不为 4期望KERNEL_STATUS_INNER_ERROR、W0期望KERNEL_STATUS_PARAM_INVALID边界场景x 分别为 0、5、15 且 W4 时的行/列换算结果row/col 均在 [0, W) 区间内。Infershape 测试tests/ut/op_host/test_coordinates_1d_to_2d_infershape.cpp通过InfershapeContextPara构造推导上下文验证输出 shape 与输入 x 一致如 x 为{100}时三个输出均为{100}、输出数据类型跟随输入 x。总结Coordinates1DTo2D 是 CANN ops-math 中一个实现简洁、语义清晰的坐标变换算子它接收 1D 线性坐标x与四维形状(N, D, H, W)通过row x / W、col x % W、n W完成向 2D 行列索引的换算广泛适用于需要将扁平索引映射回多维张量位置的场景。使用时需严格遵守三项约束shape 元素个数为 4、x 与 shape 类型一致、W 不为 0并通过图模式接口基于算子 IR 完成调用。读者可结合本仓库中的算子 IR、Infershape、AICPU 内核与完整样例进一步深入其实现细节与二次开发方法。【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考