conv2d

Description

Performs 2D convolution on an input tensor and a weight tensor and outputs a result tensor.

The following data types are supported (feature_map:weight:dst):

int8:int8:int32
float16:float16:float32

Prototype

conv2d(dst, feature_map, weight, fm_shape, kernel_shape, stride, pad, dilation, pad_value=0, init_l1out=True, bias=None)

Parameters

**Table 1** Parameter description
Parameter	Input/Output	Description
dst	Output	Start element of the destination operand. For details about the data type restrictions, see Table 2. The scope is the L1OUT Buffer. Has format [Cout/16, Ho, Wo, 16], and size *Cout Ho * Wo*, where Ho and Wo can be calculated as follows: Ho = floor((H + pad_top + pad_bottom – dilation_h (Kh – 1) – 1) / stride_h + 1) Wo = floor((W + pad_left + pad_right – dilation_w * (Kw – 1) – 1) / stride_w + 1) The hardware requires *Ho Wo to be a multiple of 16. When defining the dst tensor, shape should be rounded up to the multiple of 16. The actual shape size should be Cout * round_howo*: round_howo = ceil(Ho Wo/16) * 16 The invalid data introduced due to round-up will be removed in the subsequent fixpipe operation.
feature_map	Input	Input tensor. For the supported data types, see Table 2. The scope is the L1 Buffer.
weight	Input	Convolution kernel (weight). For the supported data types, see Table 2. The scope is the L1 Buffer.
fm_shape	Input	Shape of feature_map, in the format [C1, H, W, C0]. *C1 C0 indicates the number of input channels. If feature_map is of type float16, C0 is 16. The data type is immediate (int). If feature_map is of type int8, C0 is 32. The data type is immediate (int). C1 is an immediate in the range of [1, 256]. The number of input channels is in the range of [16 or 32, 4096]. For the first convolution on the network with float16 or int8 input, fm_shape** of conv2d supports C0 = 4 and C1 = 1. H is an immediate of type int, specifying the height. Must be in the range of [1, 4096]. W is an immediate of type int, specifying the width. Must be in the range of [1, 4096].
kernel_shape	Input	Shape of weight, in the format [C1, Kh, Kw, Cout, C0]. *C1 C0 indicates the number of input channels. If feature_map is of type float16, C0 is 16. The data type is immediate (int). If feature_map is of type int8, C0 is 32. The data type is immediate (int). C1 is an immediate of type int in the range of [1, 256]. The number of input channels is in the range of [16 or 32, 4096]. For the first convolution on the network with float16 or int8 input, kernel_shape of conv2d supports C0 = 4 and C1 = 1. Has the same number of input channels as fm_shape. Cout** is an immediate of type int specifying the number of convolution kernels. The value is a multiple of 16 in the range of [16, 4096]. Kh is an immediate of type int specifying the height of each convolution kernel. Must be in the range of [1, 255]. Kw is an immediate of type int specifying the width of each convolution kernel. Must be in the range of [1, 255].
stride	Input	Convolution stride, in the format of [stride_h, stride_w]. stride_h: an immediate of type int specifying the height stride. Must be in the range of [1, 63]. stride_w: an immediate of type int specifying the width stride. Must be in the range of [1, 63].
pad	Input	Padding factors, in the format of [pad_left, pad_right, pad_top, pad_bottom]. pad_left: an immediate of type int specifying the number of columns to be padded to the left of the feature_map. Must be in the range of [0, 255]. pad_right: an immediate of type int specifying the number of columns to be padded to the right of the feature_map. Must be in the range of [0, 255]. pad_top: an immediate of type int specifying the number of rows to be padded to the top of the feature_map. Must be in the range of [0, 255]. pad_bottom: an immediate of type int specifying the number of rows to be padded to the bottom of the feature_map. Must be in the range of [0, 255].
dilation	Input	Convolution dilation factors, in the format of [dilation_h, dilation_w] dilation_h: an immediate of type int specifying the height dilation factor. Must be in the range of [1, 255]. dilation_w: an immediate of type int specifying the width dilation factor. Must be in the range of [1, 255]. The width and height of the dilated convolution kernel is calculated as follows: *dilation_w (Kw – 1) + 1; dilation_h * (Kh – 1) + 1**
pad_value	Input	Padding value, an immediate of type int or float. Defaults to 0. If feature_map is of type int8, pad_value is an immediate of type int in the range of [–128, +127]. If feature_map is of type float16, pad_value is in the range of [–65504, +65504].
init_l1out	Input	A bool specifying whether to initialize dst. Defaults to True. True: The dst initial matrix will be overwritten by the compute result. False: The dst initial matrix stores the previous conv2d result and will be accumulated with the new conv2d result.
bias	Input	Convolutional bias. Defaults to None, indicating no bias. If bias is added, set bias to the start element of the bias operand. The data type can be Tensor (int32 or float32) and must be consistent with the data type of dst. The shape is [Cout,], where Cout indicates the number of convolution kernels. The scope is the L1 Buffer. Notes: (1) Only Atlas A2 training product / Atlas A2 inference product is supported. (2) If bias is added, init_l1out must be True. If init_1out is set to False, bias must be None.

**Table 2** Data type combination of feature_map, weight, and dst
feature_map.dtype	weight.dtype	dst.dtype
int8	int8	int32
float16	float16	float32

Applicability

Atlas training product

Atlas inference product AI Core

Atlas A2 training product / Atlas A2 inference product

Restrictions

Single-step debugging takes a long time, and is therefore not recommended.
This instruction is mutually exclusive with Vector instructions.
This instruction should be used in pair with the fixpipe instruction.
This instruction does not support the scenario where W is equal to Kw and H is greater than Kh. This will produce unexpected results.
For details about the alignment requirements of the operand address offset, see General Restrictions.

Returns

None

Example

Example: feature_map:weight:dst of type int8:int8:int32

from tbe import tik
tik_instance = tik.Tik()
# Define the tensors.
feature_map_gm = tik_instance.Tensor("int8", [1, 4, 4, 32], name='feature_map_gm', scope=tik.scope_gm)
weight_gm = tik_instance.Tensor("int8", [1, 2, 2, 32, 32], name='weight_gm', scope=tik.scope_gm)
dst_gm = tik_instance.Tensor("int32", [2, 9, 16], name='dst_gm', scope=tik.scope_gm)
feature_map = tik_instance.Tensor("int8", [1, 4, 4, 32], name='feature_map', scope=tik.scope_cbuf)
weight = tik_instance.Tensor("int8", [1, 2, 2, 32, 32], name='weight', scope=tik.scope_cbuf)
# dst has shape [2, 16, 16], where cout = 32. cout_blocks = 2, ho = 3, wo = 3, howo = 9. Therefore, round_howo = 16.
dst = tik_instance.Tensor("int32", [2, 16, 16], name='dst', scope=tik.scope_cbuf_out)
# Move data from the Global Memory to the source operand tensor.
tik_instance.data_move(feature_map, feature_map_gm, 0, 1, 16, 0, 0)
tik_instance.data_move(weight, weight_gm, 0, 1, 128, 0, 0)
# Perform convolution.
tik_instance.conv2d(dst, feature_map, weight, [1, 4, 4, 32], [1, 2, 2, 32, 32], [1, 1], [0, 0, 0, 0], [1, 1], 0)
# Move dst from L1OUT Buffer to the Global Memory by co-working with the fixpipe instruction.
# cout_blocks = 2, cburst_num = 2, burst_len = howo * 16 * src_dtype_size/32 = 9 * 16 * 4/32 = 18
tik_instance.fixpipe(dst_gm, dst, 2, 18, 0, 0, extend_params=None)
tik_instance.BuildCCE(kernel_name="conv2d", inputs=[feature_map_gm, weight_gm], outputs=[dst_gm])

Result example:

Input:
feature_map_gm:
[[[[2, 4, 2, 3, 2, ..., 3, 3, 0]]]]
weight_gm:
[[[[[-3, -5, -4, ..., -2, -4, -2]]]]]
Output:
dst_gm:
[[[-230,  -11,  -83, -103, -123, ..., -174, -255]]]

Example: feature_map:weight:dst of type float16:float16:float32

from tbe import tik
tik_instance = tik.Tik()
# Define the tensors.
feature_map_gm = tik_instance.Tensor("float16", [2, 4, 4, 16], name='feature_map_gm', scope=tik.scope_gm)
weight_gm = tik_instance.Tensor("float16", [2, 2, 2, 16, 16], name='weight_gm', scope=tik.scope_gm)
dst_gm = tik_instance.Tensor("float32", [1, 4, 16], name='dst_gm', scope=tik.scope_gm)
feature_map = tik_instance.Tensor("float16", [2, 4, 4, 16], name='feature_map', scope=tik.scope_cbuf)
weight = tik_instance.Tensor("float16", [2, 2, 2, 16, 16], name='weight', scope=tik.scope_cbuf)
# dst has shape [1, 16, 16], where cout = 16, cout_blocks = 1, ho = 2, wo = 2, howo = 4. Therefore, round_howo = 16.
dst = tik_instance.Tensor("float32", [1, 16, 16], name='dst', scope=tik.scope_cbuf_out)
# Move data from the Global Memory to the source operand tensor.
tik_instance.data_move(feature_map, feature_map_gm, 0, 1, 32, 0, 0)
tik_instance.data_move(weight, weight_gm, 0, 1, 128, 0, 0)
# Perform convolution.
tik_instance.conv2d(dst, feature_map, weight, [2, 4, 4, 16], [2, 2, 2, 16, 16], [1, 1], [0, 0, 0, 0], [2, 2], 0)
# Move dst from L1OUT Buffer to the Global Memory by co-working with the fixpipe instruction.
# cout_blocks = 1, cburst_num = 1, burst_len = howo * 16 * src_dtype_size/32 = 4 * 16 * 4/32 = 8
tik_instance.fixpipe(dst_gm, dst, 1, 8, 0, 0, extend_params=None)
tik_instance.BuildCCE(kernel_name="conv2d", inputs=[feature_map_gm, weight_gm], outputs=[dst_gm])

Result example:

Input:
feature_map_gm:
[[[[0.0, 0.01, 0.02, 0.03, 0.04, ..., 5.09, 5.1, 5.11]]]]
weight_gm:
[[[[[0.0, 0.01, 0.02, 0.03, 0.04, ..., 20.46, 20.47]]]]]

Output:
dst_gm:
[[[3568.7373, 3612.8433, 3657.0618, 3701.162 , 3745.287 ,
   3789.4834, 3833.6282, 3877.876 , 3921.9812, 3966.0745,
   4010.311 , 4054.4119, 4098.5713, 4142.702 , 4186.8457,
   4231.0312],
  [3753.9888, 3801.3733, 3848.8735, 3896.2534, 3943.6558,
   3991.1353, 4038.5586, 4086.0913, 4133.4736, 4180.8457,
   4228.3643, 4275.745 , 4323.1826, 4370.5947, 4418.016 ,
   4465.4844],
  [4309.196 , 4366.4077, 4423.745 , 4480.9565, 4538.1816,
   4595.5054, 4652.755 , 4710.135 , 4767.34  , 4824.5405,
   4881.897 , 4939.1104, 4996.374 , 5053.6226, 5110.871 ,
   5168.179 ],
  [4494.4526, 4554.944 , 4615.564 , 4676.0557, 4736.5586,
   4797.166 , 4857.695 , 4918.3604, 4978.8433, 5039.323 ,
   5099.9624, 5160.456 , 5220.999 , 5281.5293, 5342.0566,
   5402.6475]]]

Parent topic: Matrix Computation