企业官网建设流程全解析

PyPTO 逐元素向下取整运算 pypto.Tensor.floor 使用指南与实现解析

【免费下载链接】pyptoPyPTO（发音: pai p-t-o）：Parallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto

pypto.Tensor.floor是 CANN PyPTO 框架中针对 Tensor 的逐元素向下取整（floor）运算接口，对输入 Tensor 的每个元素执行向负无穷方向舍入：浮点元素向下取整，整数元素原样返回。本文基于官方 API 文档并结合仓库源码，完整介绍该接口的函数原型、参数与约束、调用示例，以及从 Python 前端到解释器后端的实现链路与测试验证，帮助开发者在 PyPTO 向量编程中正确使用取整类运算。

功能概述

floor是典型的逐元素（element-wise）一元向量运算：遍历输入 Tensor 的每一个元素，计算其向下取整值并写入输出 Tensor 的对应位置。

• 对浮点型数值（如1.2、9.8）执行向下舍入处理，结果沿数轴负方向取最近的整数；
• 对整数型数值直接返回其本身，不做任何处理。

其数学语义为：out[i] = ⌊input[i]⌋。它与同类取整运算的差异如下：

在仓库的 Tensor 类中，floor、ceil、trunc三个成员方法集中定义于 python/pypto/tensor.py，语义相互对照，便于开发者按需选用。

产品支持情况

该接口在以下硬件平台上均受支持（依据 API 文档中的产品支持声明）：

• Ascend 950PR / Ascend 950DT：支持
• Atlas A3 训练系列产品 / Atlas A3 推理系列产品：支持
• Atlas A2 训练系列产品 / Atlas A2 推理系列产品：支持

函数原型

floor同时提供 Tensor 成员方法与顶层函数两种调用形式，二者等价：

# Tensor 成员方法形式 floor(self) -> 'Tensor' # 顶层函数形式 floor(input: Tensor) -> Tensor

顶层函数定义位于 python/pypto/op/math.py，被@op_wrapper装饰并最终调用底层实现pypto_impl.Floor(input)；成员方法则是在 python/pypto/tensor.py 中通过return pypto.floor(self)直接转调顶层函数。两种写法使用哪个均可，例如x.floor()与pypto.floor(x)完全等价。

参数说明

返回值说明

返回 Tensor 类型。其 Shape、数据类型与输入 Tensor 一致，每个元素为输入 Tensor 对应元素的向下取整值。

约束说明

1. Tensor 类型输入不支持TileOpFormat.TILEOP_NZ格式，即输入需以ND（按维连续）等非 NZ 格式布局。仓库测试用例中所有 floor 用例均明确标注'format': 'ND'（见 floor_test_case.py），与这一约束一致。
2. 输入不支持空 Tensor，且 Shape 维数需控制在 1～4 维以内，总元素数不超过INT32_MAX。

调用示例

设置 TileShape

调用该 operation 接口前，应通过set_vec_tile_shapes设置向量计算的 TileShape，其维度应与输出一致。例如输入 shape 为[m, n]、输出为[m, n]，则 TileShape 设置为[m1, n1]，其中m1、n1分别用于切分m、n轴：

pypto.set_vec_tile_shapes(4, 16)

从源码看，set_vec_tile_shapes 会把各维 TileShape 写入 scope（pypto_impl.SetScope({"vec_tile_shapes": concrete_shapes})），并支持传入SymbolicScalar动态取值，为向量计算指定逐维切分粒度。实际开发中，TileShape 各维应能整除（或按切片方式覆盖）对应的数据维度，以充分发挥向量单元的分块计算能力。

接口调用示例

x = pypto.tensor([5], pypto.DT_FP32) y = pypto.floor(x)

结果示例如下：

输入数据x: [1.2, 4.3, 9.8, 16.5, 25.4] 输出数据y: [1.0, 4.0, 9.0, 16.0, 25.0]

完整内核编写示例

结合pypto.frontend.jit、pypto.loop、pypto.view与pypto.assemble，可将 floor 组织为完整的向量内核。仓库系统测试 test_floor.py 给出了标准写法：

@pypto.frontend.jit(debug_options={"runtime_debug_mode": 0, "compile_debug_mode": 0}) def floor_2d_1input_kernel(input0: pypto.Tensor(), output: pypto.Tensor(), config: FloorConfig): pypto.set_vec_tile_shapes(*config.tile_shape) for index_0 in pypto.loop(config.loop_ranges[0]): for index_1 in pypto.loop(config.loop_ranges[1]): offsets = [index_0 * config.execution_view_shape[0], index_1 * config.execution_view_shape[1]] input0_offset = [0 if config.input_shapes[0][axis] == 1 else offsets[axis] for axis in range(2)] input0_view = pypto.view(input0, config.input_view_shapes[0], input0_offset) result = pypto.floor(input0_view) output_offset = [ 0 if config.output_offset_map[axis] < 0 else offsets[config.output_offset_map[axis]] for axis in range(len(config.execution_view_shape)) ] pypto.assemble(result, output_offset, output)

该模式体现了 PyPTO 向量编程的典型四步：设置 TileShape → 双层循环遍历分块 → 用view取输入子块 → 对子块执行floor并用assemble写回输出。

底层实现链路

从源码结构可以梳理出floor的完整调用链，帮助理解其执行机制：

1. Python 前端：pypto.floor(input)（op/math.py）经由@op_wrapper包装后调用pypto_impl.Floor(input)，类型桩声明于 pypto_impl/init.pyi；
2. IR 生成：pypto_impl.Floor由 C++ 绑定层将调用转换为算子 IR 节点（对应OP_FLOOR指令）；
3. 解释器执行：IR 送入向量解释器后，由 calc_vector.cpp 中的ExecuteOpFloor处理，该函数断言输入输出各为 1 个（CTX_OUTPUT_COUNT_MISMATCH/CTX_INPUT_COUNT_MISMATCH校验），并通过REGISTER_CALC_OP(OP_FLOOR, Opcode::OP_FLOOR, ExecuteOpFloor)完成指令注册；
4. 数值计算：ExecuteOpFloor内部调用 calc.h 中的calc::Floor(out, self)，最终交由CalcOps对每个元素执行向下取整计算。

可见 floor 属于解释器内置的标准一元运算，与Ceil、Trunc、Rsqrt等共享同一套CalcOps计算设施（见 calc.h）。

测试验证

仓库为 floor 提供了完整的系统测试覆盖：

• 测试入口python/tests/st/operation/vector/test_floor.py：内核以(2, 1)（2 维、1 输入）为键注册；每个用例将输入拷贝到 NPU 设备执行内核，并以torch.floor在 CPU 侧计算期望结果，最后通过assert_outputs比对 NPU 输出与 PyTorch 期望值，完成数值一致性校验；
• 用例数据python/tests/st/operation/vector/vector_testcase/floor_test_case.py：目前包含两个用例，分别覆盖fp16与fp32两种数据类型，输入 shape 均为(16, 32)、format 为ND、数据取值范围[0, 1)，TileShape 与 view_shape 均取(16, 32)（即单块处理整张输入）；
• 测试标记：测试通过@pytest.mark.parametrize逐用例驱动，并开启pass_options={"enable_slice": True}以启用切片相关 pass 优化（见 test_floor.py）。

使用建议与注意事项

1. 数据类型选择：DT_FP32、DT_FP16、DT_BF16、DT_INT32、DT_INT16均可作为输入；整数类型输入 floor 后值不变，若确定输入恒为整数，可直接跳过取整运算以减少一次向量计算。
2. 负数的 floor 语义：floor 是向负无穷取整，负浮点数（如-1.2）结果为-2.0，与截断（trunc）不同。若业务需要向零取整，应改用trunc。
3. 布局约束：输入不支持TILEOP_NZ格式，编写内核或构造输入时请保持ND布局。
4. Shape 限制：空 Tensor 不可用，Shape 限制在 1～4 维且元素总数不超过INT32_MAX。
5. TileShape 设置：在jit内核中调用 floor 前必须先通过pypto.set_vec_tile_shapes设置 TileShape，且其维度要与输入/输出维度一致，否则切分配置可能无法正确生效。

【免费下载链接】pyptoPyPTO（发音: pai p-t-o）：Parallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto