Scatter (ISASI)

Applicability

Product	Supported
Atlas 350 Accelerator Card	√
Atlas A3 training product / Atlas A3 inference product	x
Atlas A2 training product / Atlas A2 inference product	x
Atlas 200I/500 A2 inference product	√
Atlas inference product AI Core	√
Atlas inference product Vector Core	x
Atlas training product	x

This API does not support the Atlas A2 training product / Atlas A2 inference product or Atlas A3 training product / Atlas A3 inference product . To implement data discretization on the preceding AI processors, you are advised to perform adaptation by referring to scatter compatibility sample.

Function Usage

Generates a new result tensor based on a given continuous input tensor, a destination address offset tensor, and the offset address, and distributes the input tensor to the result tensor.

Scatters elements in the source operand src to positions (specified by using dst_offset and base_addr) in the destination operand dst.

Prototype

Computation of the first n data elements of a tensor

        
             template <typename T>
__aicore__ inline void Scatter(const LocalTensor<T>& dst, const LocalTensor<T>& src, const LocalTensor<uint32_t>& dstOffset, const uint32_t dstBaseAddr, const uint32_t count)

High-dimensional tensor sharding computation

Bitwise mask mode

          
               template <typename T>
__aicore__ inline void Scatter(const LocalTensor<T>& dst, const LocalTensor<T>& src, const LocalTensor<uint32_t>& dstOffset, const uint32_t dstBaseAddr, const uint64_t mask[], const uint8_t repeatTime, const uint8_t srcRepStride)

Contiguous mask mode

          
               template <typename T>
__aicore__ inline void Scatter(const LocalTensor<T>& dst, const LocalTensor<T>& src, const LocalTensor<uint32_t>& dstOffset, const uint32_t dstBaseAddr, const uint64_t mask, const uint8_t repeatTime, const uint8_t srcRepStride)

Parameters

**Table 1** Parameters in the template
Parameter	Description
T	Operand data type. For the Atlas 350 Accelerator Card, the supported data types are uint8_t, int8_t, uint16_t, int16_t, half, bfloat16_t, uint32_t, int32_t, float, uint64_t, and int64_t. For the Atlas 200I/500 A2 inference product , the supported data types are uint8_t, int8_t, uint16_t, int16_t, half, uint32_t, int32_t, and float. For the Atlas inference product AI Core, the supported data types are uint16_t, uint32_t, float, and half.

**Table 2** Parameters
Parameter	Input/Output	Meaning
dst	Output	Destination operand, which is of the LocalTensor type. The start address of LocalTensor must be 32-byte aligned.
src	Input	Source operand of the LocalTensor type. Its data type must be the same as that of dst.
dstOffset	Input	It is used to store the address offset of each element of the source operand in dst. The offset is calculated based on the base address dstBaseAddr of dst and is expressed in bytes. The value must be aligned based on the bit width of the dst data type. Otherwise, unexpected behavior may occur. For the following models, the value range of the address offset must be within the range of uint32_t. Atlas inference product AI Core For the following models, the address offset must be within the range of [0, 2¹⁶ – 1] when the operand is 8-bit, within the range of [0, 2¹⁷ – 1] when the operand is 16-bit, and within the range of uint32_t when the operand is 32-bit or 64-bit. If the value is out of the range, unexpected output may occur. Atlas 200I/500 A2 inference product Atlas 350 Accelerator Card
dstBaseAddr	Input	Start offset of dst, in bytes. Ensure that the bit width of the dst data type is aligned. Otherwise, unexpected behavior occurs.
count	Input	Number of data elements to be processed.
mask/mask[]	Input	mask controls the elements that participate in computation in each iteration. Contiguous mode: indicates the number of contiguous elements that participate in computation. The value range is related to the operand data type. The maximum number of elements that can be processed in each repeat varies according to the data type. When the operand is 8-bit or 16-bit, mask ∈ [1, 128]. When the operand is 32-bit, mask ∈ [1, 64]. When the operand is 64-bit, mask ∈ [1, 32]. Bitwise mode: controls the elements that participate in computation by bit. If a bit is set to 1, the corresponding element participates in the computation. If a bit is set to 0, the corresponding element is masked in the computation. The parameter type is a uint64_t array with a length of 2. For example, if mask = [0, 8] and 8 = 0b1000, only the fourth element participates in computation. The parameter value range is related to the operand data type. The maximum number of elements that can be processed in each repeat varies according to the data type. When the operand is 8-bit or 16-bit, mask[0] and mask[1] ∈ [0, 2⁶⁴ – 1] and cannot be 0 at the same time. When the operand is 32-bit, mask[1] is 0 and mask[0] ∈ (0, 2⁶⁴ – 1]. When the operand is 64-bit, mask[1] is 0 and mask[0] ∈ (0, 2³² – 1].
repeatTime	Input	Number of instruction iterations. Data of eight data blocks is collected in each iteration. Data range: repeatTime ∈ [0,255] For the following models: Atlas 200I/500 A2 inference product Atlas 350 Accelerator Card When the operand is 8-bit, four data blocks (32 bytes) are collected in each repeat.
srcRepStride	Input	Address stride of the operand between adjacent iterations. The unit is data block.

Restrictions

For details about the operand address alignment requirements, see General Address Alignment Restrictions.
For details about the constraints on operand address overlapping, see General Address Overlapping Restrictions.

The offset addresses in dstOffset must be unique. If two or more offsets are the same, the behavior is unpredictable.
For the Atlas 350 Accelerator Card, only the APIs that compute the first n data elements of a tensor are supported for the uint8_t and int8_t data types.

Examples

      
           uint32_t m_elementCount = 128;
AscendC::Scatter(dstLocal, srcLocal, dstOffsetLocal, (uint32_t)0, m_elementCount); // dstOffsetLocal stores the address offset of each element of the source operand in dst.

Result example:

Input dstOffsetLocal:
[254 252 250 ... 4 2 0]
Input srcLocal (128 data elements of the half type):
[0 1 2 ... 125 126 127]
Output dstGlobal:
[127 126 125 ... 2 1 0]

Parent topic: Data Padding