for_range

功能说明

代表tik的for循环语句，可在for循环中开启n buffer和多核运行功能。

函数原型

for_range(begint, endt, name="i", thread_num=1, thread_type="whole", block_num=1,dtype="int32", subblock_num=0, sub_dtype="int32", for_type="serial", enable_subblk=False)

参数说明

表1 参数说明
参数名称	输入/输出	含义
begint	输入	for_range循环变量起始值。 begint和endt为立即数（int, uint）、Scalar（int, uint）、Expr，Expr化简后的值也需要为整数，需要满足 0<=begint<=endt<=2147483647。循环变量的取值大于等于begint且小于endt。
endt	输入	for_range循环变量结束值。 begint和endt为立即数（int, uint）、Scalar（int, uint）、Expr，Expr化简后的值也需要为整数，需要满足 0<=begint<=endt<=2147483647。循环变量的取值大于等于begint且小于endt。说明： begint和endt使用Scalar，性能会有所下降。
name	输入	for_range循环中的循环变量名字。说明：为方便后续算子编译时的问题定位，建议用户配置此参数，且值保持唯一。在算子实现代码中有多个for_range语句时，若用户未配置name，则循环变量的名字默认设置为“i”，“j”,“k”，......
thread_num	输入	for_range循环中是否开启n buffer。类型为立即数，取值： 0：表示强制不开启n buffer，即使外层for_range()开启了n buffer，本层不受外层影响，不会开启n buffer。 1：表示不开启n buffer，如果外层的for_range()开启了n buffer，本层受外层影响，在内存空间足够的情况下，本层会开启 n buffer。 2：表示开启2 buffer 3：表示开启3 buffer 4：表示开启4 buffer 说明： 3和4只有在算子类型为纯搬运类算子，且追求极致性能的场景下才会用到，一般算子进行性能优化，仅开启2 buffer即可。不支持该功能的处理器型号为： Atlas 200I/500 A2推理产品
thread_type	输入	代表for_range循环展开的代码排列方式，当前为保留参数，对运行无影响。取值：whole
block_num	输入	for_range循环中使用的核数。类型为立即数，取值范围为[1, 65535]。当此处配置的核数大于当前可用的核数时，runtime会分批调度执行。当此处配置的核数小于等于当前可用的核数时，runtime也会根据实际情况调度执行，实际运行的核数可能小于等于此处配置的核数。
dtype	输入	for_range循环变量的类型，当前为保留参数，对运行无影响。取值：int32
subblock_num	输入	AIC/AIV多核结构中，Cube与Vector Core可按组进行划分。一个组内可以分为主核block及从核subblock，block与subblock比例为1:N（N>=1）。subblock_num即为从核的for循环中使用的核数。类型为立即数，取值范围为[2, 65535]，不开启时默认为0。注意：配置的从核数量需要小于或等于实际硬件可分配的从核数量，即block_num * subblock_num <= 实际硬件核数量。该参数支持的AI处理器型号： Atlas A2训练系列产品 Atlas 200I/500 A2推理产品
sub_dtype	输入	从核for_range循环变量的类型，当前为保留参数，对运行无影响。取值：int32 该参数支持的AI处理器型号： Atlas A2训练系列产品 Atlas 200I/500 A2推理产品
for_type	输入	代表此for_range循环本身的类型，取值：serial
enable_subblk	输入	启用从核循环标志，默认为False，开启时修改为True 该参数支持的AI处理器型号： Atlas A2训练系列产品 Atlas 200I/500 A2推理产品

支持的型号

Atlas 200/300/500 推理产品

Atlas 训练系列产品

Atlas推理系列产品（Ascend 310P处理器）AI Core

Atlas推理系列产品（Ascend 310P处理器）Vector Core

Atlas A2训练系列产品

Atlas 200I/500 A2推理产品

注意事项

在for_range循环内，如果存在嵌套循环，只允许最外层循环开启多核。
如果开启多核，多核循环起始值必须为0，多核的核数和循环的终止值必须相等且数据类型必须相同，都为int。
在一个for_range循环内，不能同时开启多核和n buffer。如果想同时开启多核和n buffer，采用多个循环方式。
如果开启多核，在多核循环内使用到的tensor，必须要定义在多核循环内。因为多核循环外和多核循环内的tensor内存分配同时从0开始分配，可能导致地址重叠，最后导致数据错误。
一个算子中只能调用一次for_range开启block多核，即设置block_num >=2并与循环次数保持一致，不允许多次开启。但针对Atlas A2训练系列产品，可以同时开启block及subblock多核。
开启n buffer时，只有定义在for_range循环内的tensor ，才会分配多份内存。
循环的执行体内不能修改for_range的endt值，否则会导致算子执行任务挂起。
当begint和endt为scalar时，其范围检查会自动将begint从0开始计数，最终的endt为 endt - begint。此时，满足调整后的范围为0<=begint<=endt<=2147483647即可。
当 0 < endt - begint < thread_num，编译会报错
针对Atlas A2训练系列产品，subblock内不能同时包含AIC和AIV的运算。
针对Atlas A2训练系列产品，subblock可以在算子内单独调用或者嵌套在block内，非法嵌套会报错。
针对Atlas A2训练系列产品，单个算子或单个block内多次调用subblock循环时，每个循环调用核数subblock_num需要一致。
Atlas 200I/500 A2推理产品，subblock内不能同时包含AIC和AIV的运算。
Atlas 200I/500 A2推理产品，subblock可以在算子内单独调用或者嵌套在block内，非法嵌套会报错。
Atlas 200I/500 A2推理产品，subblock可以在算子内单独调用或者嵌套在block内，非法嵌套会报错。

使用循环变量时的注意事项：

# 使用循环变量
with self.tik_instance.for_range(0,10) as i:
    with self.tik_instance.if_scope(i==0):    # 注意不能使用if i==0:
        do_something
    with self.tik_instance.else_scope():    # 注意不能使用else:
        do_something

返回值

TikWithScope对象

调用示例

 with self.tik_instance.for_range(0,1,thread_num=1):
    do_something

# 开启double buffer，注意，tensor的定义要在for range内部定义才能会分配2份内存
 with self.tik_instance.for_range(0,2,thread_num=2): 
    tensor定义
    do_something

# 开启多核运行
 with self.tik_instance.for_range(0,2,block_num=2): 
    do_something

针对Atlas A2训练系列产品，开启多个从核运行示例：

 with self.tik_instance.for_range(0,2,subblock_num=2, enable_subblk=True) as subblockIdx: 
    do_something

# 嵌套主核从核运行
 with tik_instance.for_range(0, 2, block_num=2) as block_idx:
     with tik_instance.for_range(0, 2, subblock_num=2, enable_subblk=True) as subblockIdx:
         do_something()

父主题： 程序控制