PyPTO 循环控制进阶指南:从基础 for 循环到循环展开与编译期调试
PyPTO 循环控制进阶指南:从基础 for 循环到循环展开与编译期调试
导读
PyPTO(Parallel Tensor/Tile Operation)是 CANN 生态中面向 NPU 的张量/分块(Tile)编程范式。在 PyPTO JIT 内核中,pypto.loop 构建的循环不仅是数据遍历结构,更是参与编译期优化与代码生成的关键控制流。本文以仓库中的 loop 示例 及其配套 README_en.md 为核心,系统讲解循环的 start/stop/step 三参数用法、循环起止判断、循环展开(unroll)优化、算子必须位于最内层循环的放置规则,以及内核循环内 print 的编译期行为。读完本文,你将能独立编写、调试和优化包含多层循环的 PyPTO 算子内核,并理解这些循环规则背后的源码级原理。
示例概述与代码结构
本示例聚焦于 PyPTO JIT 内核中循环的高级特性及其在算子内核中的使用规则,覆盖以下关键点:
- 基础循环用法:
start、end、step三个参数的使用方式; - 循环起止判定:如何确定循环的开始与结束;
- 循环展开:通过
unroll接口优化性能; - 算子位置规则:算子通常必须放置在最内层循环中,以保证正确的代码生成;
- 编译期打印:内核循环中的
print只在编译期执行。
示例代码文件为 loop.py,包含 4 个互相独立的测试用例:
| 测试函数 | 说明 |
|---|---|
test_loop_basic |
基础循环用法(start/stop/step) |
test_loop_compile_phase_print |
编译期打印特性 |
test_add_scalar_loop |
标量加法循环示例(循环 + 标量累加) |
test_add_scalar_loop_dyn_axis |
动态轴下的标量加法循环示例 |
其中 test_add_scalar_loop 与 test_add_scalar_loop_dyn_axis 是同一算子的两种写法:前者直接用切片(slice)划分子张量,后者在动态 batch 轴上用 pypto.view + pypto.assemble 结合 valid_shape 处理边界,是理解“循环驱动分块(tiling)”的典型样例。
运行环境准备与执行
配置 CANN 环境变量
示例运行前需先配置 CANN 环境变量。以默认路径安装、root 用户为例(非 root 用户请将 /usr/local 替换为 ${HOME}):
# 配置 CANN 环境变量(set_env.sh 实际路径请以安装为准)
# 该配置仅对当前终端窗口生效,可按需写入 ~/.bashrc 等环境变量配置文件
source /usr/local/Ascend/ascend-toolkit/set_env.sh
# 设置设备 ID
export TILE_FWK_DEVICE_ID=0
TILE_FWK_DEVICE_ID 是示例脚本读取设备号的环境变量:在 loop.py 的 get_device_id() 中,若该变量未设置或不是合法整数,脚本会打印提示并直接返回,因此该变量是 NPU 模式下运行的前提。设备号随后会通过 torch.npu.set_device(device_id) 完成设备绑定。
执行脚本与用例选择
# 运行全部循环特性用例
python3 loop.py
# 列出所有可用用例及其 ID
python3 loop.py --list
main() 中注册了 4 个用例(loop.py),除 --list 外,还支持两种用法:
# 只运行指定用例
python3 loop.py loop_basic::test_loop_basic
python3 loop.py add_scalar_loop::test_add_scalar_loop
# 指定运行模式:npu(默认)或 sim(仿真)
python3 loop.py --run_mode sim
--run_mode支持npu与sim两种取值,脚本在导入阶段即通过_peek_run_mode_from_argv()提前解析该参数,以决定顶层装饰器@pypto.frontend.jit(runtime_options={"run_mode": ...})绑定的运行模式(loop.py);- 传入非法用例 ID 时脚本会打印合法 ID 列表并退出(loop.py)。
核心概念与规则
1. 基础用法:start / stop / step
pypto.loop 的用法与 Python 内建 range 类似,最基础的形态如下:
for i in pypto.loop(start=0, end=10, step=1):
# 循环体逻辑
从源码看,loop() 支持 1~3 个位置参数,通过 _get_loop_range() 归一化(python/pypto/_controller.py):
- 1 个参数:
pypto.loop(stop),等价于range(stop),即start=0, step=1; - 2 个参数:
pypto.loop(start, stop),step取默认值 1; - 3 个参数:
pypto.loop(start, stop, step),三者全显式指定。
循环范围遵循 Python 语义:stop 为开区间(exclusive)。在 loop.py 的 loop_basic_kernel 中可以看到两种形态的实战用法:
for bs_idx in pypto.loop(0, n, 1): # 显式 start/stop/step
t0s = t0[bs_idx * s:(bs_idx + 1) * s, :]
t1s = t1[bs_idx * s:(bs_idx + 1) * s, :]
out0[bs_idx * s:(bs_idx + 1) * s, :] = pypto.add(t0s, t1s)
new_step = 2
for bs_idx in pypto.loop(0, n, new_step): # step 为编译期常量
t0s = t0[bs_idx * s:(bs_idx + new_step) * s, :]
t1s = t1[bs_idx * s:(bs_idx + new_step) * s, :]
out1[bs_idx * s:(bs_idx + new_step) * s, :] = pypto.add(t0s, t1s)
该内核先用 step=1 逐块累加得到 out0,再用 step=2 每轮跨越 2 个 tile 累加得到 out1。test_loop_basic 会同时用 assert max_diff < 1e-2 校验两个输出与 torch 参考值的一致性,并验证两个输出之间的差异小于 1e-6(loop.py),以此证明 step 改变的是“每次迭代覆盖的数据块大小”,而非计算语义。
底层实现上,pypto.loop 返回一个生成器,其每次迭代产生一个符号整数(SymbolicScalar)作为循环索引;该索引携带 _loop_begin/_loop_end 属性,供 is_loop_begin/is_loop_end 使用(python/pypto/_controller.py)。
注意:
loop的step必须是常量。这是 README_en.md 明确列出的注意事项——step 参与编译期的循环结构生成,若为运行期变量,将无法在编译期确定循环展开与分块结构。
2. 循环起止判定:is_loop_begin / is_loop_end
PyPTO 提供两个辅助接口用于在循环体内判断当前迭代是否处于循环边界:
for s2_idx in pypto.loop(bn_per_batch):
if pypto.cond(pypto.is_loop_begin(s2_idx)):
# 循环首迭代特殊处理(如初始化)
...
if pypto.cond(pypto.is_loop_end(s2_idx)):
# 循环末迭代特殊处理(如收尾)
...
两者的底层语义在 python/pypto/pil/ops.py 中实现:
is_loop_begin(scalar):判定scalar == start,即当前索引是否等于循环起始值;is_loop_end(scalar):判定scalar + step >= end,即当前索引是否进入最后一个迭代。
这两个接口通常与 pypto.cond 配合,构成编译期可解析的条件分支,用于在循环首尾插入不同的计算逻辑(如流水线 prolog/epilog)。在 python/pypto/_controller.py 中,若传入的标量并非循环索引(缺少 _loop_begin/_loop_end 属性),接口会直接抛出 ValueError。
3. 算子位置规则:置于最内层循环
为确保计算指令被正确分块并生成高性能 NPU 代码,应将计算算子(如 add、matmul 等)放置在内核的最内层循环中。
这条规则与 PyPTO 的代码生成模型直接相关:pypto.loop 的循环会在编译期被展开为硬件循环结构,外层循环负责 tile 的搬运与调度,而算子(如 pypto.add)真正发射向量/标量计算指令;只有算子位于最内层,其输入输出 tile 的 shape 才可能在编译期完全确定,从而支撑精确的指令调度与向量化。示例中的 loop_compile_phase_print_kernel 展示了嵌套循环形态:
for outside_idx in pypto.loop(5):
for inside_idx in pypto.loop(3):
res = pypto.add(in_t0, in_t0) # 算子位于最内层循环
...
out_t0.move(pypto.add(in_t0, in_t0))
此外,循环结构会直接影响 tiling 策略的执行:复杂循环嵌套可能要求更细粒度的 tiling 配置。示例中通过 pypto.set_vec_tile_shapes(64, 64)(或 (1, 4, 1, 64))设定向量计算的 tile 形状,该接口在 python/pypto/_controller.py 中实现,用于指定向量计算各维度的分块大小。例如 loop_basic_kernel 中设置 (64, 64) 后,循环每轮恰好处理一个 (s, s) = (64, 64) 的数据块;而 add_kernel 中设置 (1, 4, 1, 64),与 tile_b = 1 的 batch 分块一一对应。
4. 编译期打印:print 只在编译阶段执行
在 pypto.loop 内部直接使用 print() 时,打印行为发生在编译阶段而非运行阶段:
- 它无法打印运行期张量的真实数值;
- 它只能辅助调试编译路径本身(例如查看循环索引的符号表达式、子图生成顺序等)。
示例 loop_compile_phase_print_kernel 完整演示了这一行为(loop.py):
@pypto.frontend.jit(runtime_options={"run_mode": global_run_mode})
def loop_compile_phase_print_kernel(
in_t0: pypto.Tensor(), in_t1: pypto.Tensor(), out_t0: pypto.Tensor(), out_t1: pypto.Tensor()
):
pypto.set_vec_tile_shapes(64, 64)
note = '''
Below are demonstrations of print usage within loops.
It executes only during compilation, cannot truly print variable values,
and the number of prints is related to the number of subgraphs generated.
'''
print(note)
print("*" * 60)
cnt_inside_cond = 0
cnt_outside_cond = 0
for outside_idx in pypto.loop(5):
print(f"outside_idx: {outside_idx}")
for inside_idx in pypto.loop(3):
print(f"inside_idx: {inside_idx}")
res = pypto.add(in_t0, in_t0)
print(f"res: {res}")
if outside_idx < 3:
print(f"(outside_idx < 3)_count: {cnt_outside_cond}")
cnt_outside_cond = cnt_outside_cond + 1
res = pypto.add(in_t0, in_t0)
else:
res = pypto.sub(in_t0, in_t0)
if inside_idx < 2:
print(f"(inside_idx < 2)_count: {cnt_inside_cond}")
cnt_inside_cond = cnt_inside_cond + 1
res = pypto.div(in_t0, in_t0)
else:
res = pypto.add(in_t1, in_t1)
out_t0.move(pypto.add(in_t0, in_t0))
out_t1.move(pypto.add(in_t1, in_t1))
print("*" * 60)
其中 print(f"res: {res}") 打印的是符号表达式而非数值;print(f"outside_idx: {outside_idx}") 打印的也是循环索引的符号表示。代码注释明确指出:打印次数与编译期生成的子图数量相关——pypto.loop 在编译期会按需拆分为若干子图(subgraph),print 随每个子图的构建执行一次,因此实际输出次数并不等于循环迭代次数。
test_loop_compile_phase_print 在编译期打印之外,还会在运行期校验 out_t0 ≈ in_t0 + in_t0、out_t1 ≈ in_t1 + in_t1(loop.py),说明循环体内的分支计算并不影响最终 move 到输出的结果,帮助读者区分“编译期控制流”与“运行期数据流”两个层面。
5. 循环展开:unroll 优化
对于迭代次数较少的循环,可以使用循环展开(unroll)技术减少分支开销。
PyPTO 提供两种使用方式:
方式一:loop() 的 unroll_list 参数
for i in pypto.loop(0, n, 1, unroll_list=[4, 2, 1]):
# 循环体逻辑
方式二:loop_unroll() 接口
for idx in pypto.loop_unroll(0, 10, 1, name="LOOP_L0_bIdx",
idx_name="bIdx", unroll_list=[4, 2, 1]):
b[:] = a + idx
loop_unroll 与 loop 几乎相同,仅多出 unroll_list 参数。其实现位于 python/pypto/_controller.py:
unroll_list默认值为[1](即不展开);- 传入的展开因子会被
sorted(set(...), reverse=True)降序去重,并强制补入1; - 按因子从大到小依次生成循环段:
step = step * factor,余数部分((stop - start) % nstep)单独循环处理; - 每个展开段在编译期把循环体重复展开
factor次(见 python/pypto/pil/ops.py 中_loop_unroll的for i in range(factor)展开逻辑),从而减少循环分支判断与跳转开销; - 命名上,展开段会附加
_LoopUnroll{factor}后缀(如LOOP_L0_bIdx_LoopUnroll4),后端据此解析unroll_times属性。
展开因子的合法性校验在 python/pypto/pil/ops.py 完成:必须是正整数,否则抛出 ValueError。
适用场景:unroll 适合迭代次数少、循环体短小、分支开销占比高的循环。对于迭代次数多的大循环,展开会显著膨胀代码体积,需权衡使用。
动态轴场景:循环驱动分块与 view/assemble
test_add_scalar_loop 与 test_add_scalar_loop_dyn_axis 展示了循环在动态 shape 下的典型分块模式,这是 PyPTO tile 编程的精髓:用循环遍历 batch 维度,每轮只处理一个 tile,再通过 assemble 写回输出。
两个用例共享相同的算子语义:output = input0 + input1 + val,输入 shape 为 (32, 32, 1, 256),val 为标量。不同点在于动态轴的处理方式。
静态轴版本 add_kernel(loop.py):
@pypto.frontend.jit(runtime_options={"run_mode": global_run_mode})
def add_kernel(
input0: pypto.Tensor([pypto.DYNAMIC, ...], pypto.DT_FP32),
input1: pypto.Tensor([pypto.DYNAMIC, ...], pypto.DT_FP32),
output: pypto.Tensor([pypto.DYNAMIC, ...], pypto.DT_FP32),
val: int,
):
pypto.set_vec_tile_shapes(1, 4, 1, 64)
b = input0.shape[0]
tile_b = 1
b_loop = b // tile_b
for idx in pypto.loop(b_loop):
b_offset = idx * tile_b
b_offset_end = (idx + 1) * tile_b
t0_sub = input0[b_offset:b_offset_end, ...]
t1_sub = input1[b_offset:b_offset_end, ...]
t3_sub = t0_sub + t1_sub
t3_sub = t3_sub + val
pypto.assemble(t3_sub, [b_offset, 0, 0, 0], output)
要点:
- 张量声明使用
[pypto.DYNAMIC, ...]表示首维动态,pypto.DT_FP32指定数据类型; b = input0.shape[0]取运行期 batch 值,b_loop = b // tile_b计算循环轮数——这是运行期动态值驱动编译期循环结构的体现;- 循环内用 Python 切片提取
(tile_b, w, n, c)子块,做两次加法后,用pypto.assemble(t3_sub, [b_offset, 0, 0, 0], output)将子块写回输出张量的对应偏移位置。
动态轴版本 add_scalar_loop_dynamic_axis_kernel(loop.py):
@pypto.frontend.jit(runtime_options={"run_mode": global_run_mode})
def add_scalar_loop_dynamic_axis_kernel(
input0: pypto.Tensor([pypto.DYNAMIC, ...], pypto.DT_FP32),
input1: pypto.Tensor([pypto.DYNAMIC, ...], pypto.DT_FP32),
output: pypto.Tensor([pypto.DYNAMIC, ...], pypto.DT_FP32),
val: int,
):
pypto.set_vec_tile_shapes(1, 4, 1, 64)
b, w, n, c = input0.shape
tile_b = 1
b_loop = b // tile_b
for idx in pypto.loop(b_loop):
b_offset = idx * tile_b
b_offset_end = min((idx + 1) * tile_b, b)
valid_shape = [b_offset_end - b_offset, w, n, c]
t0_sub = pypto.view(input0, [tile_b, w, n, c], [b_offset, 0, 0, 0], valid_shape=valid_shape)
t1_sub = pypto.view(input1, [tile_b, w, n, c], [b_offset, 0, 0, 0], valid_shape=valid_shape)
t3_sub = t0_sub + t1_sub
t3_sub = t3_sub + val
pypto.assemble(t3_sub, [b_offset, 0, 0, 0], output)
与静态版本的区别:
b, w, n, c = input0.shape直接解包四维 shape;- 通过
pypto.view(tensor, shape, offsets, valid_shape=...)显式声明视图的目标 shape 与偏移,并用valid_shape描述实际有效区域(此处min((idx + 1) * tile_b, b)处理 batch 末尾不足一个 tile 的边界情况); - 视图计算完成后,同样以
pypto.assemble(t3_sub, [b_offset, 0, 0, 0], output)按偏移写回。
两个用例在 NPU 模式下都会与 torch.add(x, y) + val 的 golden 值做 assert_allclose 对比(rtol/atol 均为 3e-3,见 loop.py),确保循环 + 分块写回的结果与 PyTorch 参考实现一致。
循环内建工具与更细的用法扩展
除本文示例直接使用的接口外,PyPTO 还提供与循环相关的辅助能力,便于读者进一步深入:
pypto.cond(condition):构建编译期条件分支,配合if/elif/else使用。示例循环体中的if outside_idx < 3:即被前端翻译为基于cond的分支结构(python/pypto/_controller.py);pypto.is_loop_begin / is_loop_end:见上文“循环起止判定”一节,用于边界特殊处理;pypto.loop的其他关键字:name(循环名,如"LOOP_L0_bIdx")、idx_name(索引名)、submit_before_loop(循环前插入 barrier)、parallel(并行标记)等,均通过 kwargs 透传给底层RecordLoopFunc(python/pypto/_controller.py);- 循环类型:从 python/pypto/pil/pir.py 的
LoopKind枚举可见,PyPTO 支持FOR(静态 for)、WHILE(静态 while)与DYNAMIC_FOR(pypto.loop,编译为硬件 for)三类;其中DYNAMIC_FOR形态不支持 Python 风格的break/continue,这是与普通 Python 循环的重要区别。
注意事项汇总
- step 必须是常量:
pypto.loop的step参与编译期循环结构生成,运行期变量无法作为 step; - 算子放置在最内层:计算算子必须位于最内层循环,才能被正确 tiling 并生成高性能 NPU 指令;
- 循环结构影响 tiling:循环嵌套直接影响 tiling 策略的执行,复杂嵌套可能需要更细粒度的 tiling 配置(如调整
pypto.set_vec_tile_shapes的各维分块值); - print 是编译期行为:
print只在编译阶段执行,无法打印运行期张量数值,打印次数与生成的子图数量相关; DYNAMIC_FOR不支持 break/continue:pypto.loop编译为硬件循环结构,循环体内的break/continue不会被按 Python 语义处理。
源码延伸阅读
若希望深入理解循环的底层实现,可进一步阅读以下源码与测试:
- 循环 API 定义与实现:python/pypto/_controller.py(
LoopRange、loop、loop_unroll、is_loop_begin、is_loop_end) - 前端 PIL 循环展开与条件分支实现:python/pypto/pil/ops.py
- 循环 IR 数据结构与类型枚举:python/pypto/pil/pir.py
- 类型桩文件(供 IDE 提示):python/pypto/pypto_impl/init.pyi
- 示例脚本与文档:loop.py、README_en.md
- 关联控制流示例(条件分支、动态 shape):condition.py、dynamic.py
通过本示例,你可以掌握 PyPTO 内核中循环控制的核心规则:用 start/stop/step 精确控制迭代范围,将算子收敛到最内层循环以获得正确高效的代码生成,利用 unroll_list 或 loop_unroll 在迭代次数少的场景中削减分支开销,并借助编译期 print 与 is_loop_begin/is_loop_end 完成对编译路径的调试和边界控制。