Compares (Flexible Scalar Position)

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	x
Atlas inference product AI Core	x
Atlas inference product Vector Core	x
Atlas training product	x

Function Usage

Performs comparison between each element of a tensor and a scalar, with a flexible scalar position (before or after a tensor). The scalar input can also be a single element from a LocalTensor. idx indicates the position index of a LocalTensor single element.

$\text{[math]}$

The following comparison modes are supported:

LT: less than
GT: greater than

GE: greater than or equal to
EQ: equal to
NE: not equal to
LE: less than or equal to

Prototype

Computation of the first n pieces of data of a tensor

        
             template <typename T0 = BinaryDefaultType, typename T1 = BinaryDefaultType, bool isSetMask = true, const BinaryConfig &config = DEFAULT_BINARY_CONFIG, typename T2, typename T3, typename T4>
__aicore__ inline void Compares(const T2& dst, const T3& src0, const T4& src1, CMPMODE cmpMode, uint32_t count)

High-dimensional tensor sharding computation

Bitwise mask mode

          
               template <typename T0 = BinaryDefaultType, typename T1 = BinaryDefaultType, bool isSetMask = true, const BinaryConfig &config = DEFAULT_BINARY_CONFIG, typename T2, typename T3, typename T4>
__aicore__ inline void Compares(const T2& dst, const T3& src0, const T4& src1, CMPMODE cmpMode, const uint64_t mask[], uint8_t repeatTime, const UnaryRepeatParams& repeatParams)

Contiguous mask mode

          
               template <typename T0 = BinaryDefaultType, typename T1 = BinaryDefaultType, bool isSetMask = true, const BinaryConfig &config = DEFAULT_BINARY_CONFIG, typename T2, typename T3, typename T4>
__aicore__ inline void Compares(const T2& dst, const T3& src0, const T4& src1, CMPMODE cmpMode, const uint64_t mask, uint8_t repeatTime, const UnaryRepeatParams& repeatParams)

Parameters

Table 1 Template parameters

Parameter

Description

Data type of the source operands for an API with a fixed scalar position.

For an API with a flexible scalar position, this parameter is reserved for future use. If this parameter needs to be specified, pass the default value BinaryDefaultType.

Data type of the destination operand for an API with a fixed scalar position.

For an API with a flexible scalar position, this parameter is reserved for future use. If this parameter needs to be specified, pass the default value BinaryDefaultType.

isSetMask

Indicates whether to set mask inside the API.

true: sets mask inside the API.
false: sets mask outside the API. Developers need to use the SetVectorMask API to set the mask value. In this mode, the mask value in the input parameter of this API must be set to the placeholder MASK_PLACEHOLDER.

config

Position of a single element. This parameter is of BinaryConfig type and takes effect when the scalar input is a LocalTensor single element. The default value is DEFAULT_BINARY_CONFIG, indicating that the scalar is after the tensor.

           
                struct BinaryConfig {
    int8_t scalarTensorIndex = 1; // Position of the scalar when the scalar input is a LocalTensor single element. 0 indicates the scalar is before the tensor and 1 indicates the scalar is after the tensor.
};
constexpr BinaryConfig DEFAULT_BINARY_CONFIG = {1};

LocalTensor data type. The data type is automatically inferred based on dst. Developers do not need to configure this parameter. Ensure that dst meets the data type requirements.

LocalTensor or scalar data type. The data type is automatically inferred based on src0. Developers do not need to configure this parameter. Ensure that src0 meets the data type requirements.

LocalTensor or scalar data type. The data type is automatically inferred based on src1. Developers do not need to configure this parameter. Ensure that src1 meets the data type requirements.

**Table 2** API parameters
Parameter	Input/Output	Meaning
dst	Output	Destination operand. The type is LocalTensor, and TPosition can be VECIN, VECCALC, or VECOUT. The start address of LocalTensor must be 32-byte aligned. dst is used to store the comparison result. The uint8_t data in dst is expanded bit-wise, with each bit from left to right representing the comparison result of the corresponding positions in src0 and src1. If the comparison result is true, the corresponding bit is set to 1; otherwise, it is set to 0. For the Atlas 350 Accelerator Card, the supported data type is uint8_t.
src0/src1	Input	Source operands. If the scalar input is a LocalTensor, the source operands are a vector operand and a single element from the LocalTensor. TPosition can be VECIN, VECCALC, or VECOUT. The start address of LocalTensor must be 32-byte aligned. For the Atlas 350 Accelerator Card, the supported data types are int8_t, uint8_t, int16_t, uint16_t, half, bfloat16_t, int32_t, uint32_t, float, int64_t, uint64_t, and double (double only supports CMPMODE::EQ). If the scalar input is an immediate value: For the Atlas 350 Accelerator Card, the supported data types are int8_t, uint8_t, int16_t, uint16_t, half, bfloat16_t, int32_t, uint32_t, float, int64_t, uint64_t, and double (double only supports CMPMODE::EQ). The data type must be the same as that of the destination operand.
cmpMode	Input	Comparison mode, including EQ, NE, GE, LE, GT, and LT. LT: src0 < src1 GT: src0 > src1 GE: src0 ≥ src1 EQ: src0 = src1 NE: src0 ≠ src1 LE: src0 ≤ src1
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 depends on the operand data type. The maximum number of elements that can be processed in each iteration varies depending on the data type. If the operand is 16-bit, mask is in the range [1, 128]. If the operand is 32-bit, mask is in the range [1, 64]. Bitwise mode: controls which elements participate in the computation on a per-bit basis. A bit value of 1 indicates participation, while 0 indicates non-participation. The parameter type is a uint64_t array of length 2 or 4. For example, if mask = [0, 8] and 8 = 0b1000, only the fourth element participates in computation. The value range depends on the operand data type. The maximum number of elements that can be processed in each iteration varies depending on the data type. If the operand is 16-bit, mask[0] and mask[1] are in the range [0, 2⁶⁴ – 1] and cannot be 0 at the same time. If the operand is 32-bit, mask[1] is 0 and mask[0] is in the range (0, 2⁶⁴ – 1].
repeatTime	Input	Number of iteration repeats. The Vector Unit reads 256 bytes of contiguous data for computation each time. To read the complete data for processing, the unit needs to read the input data in multiple repeats. repeatTime indicates the number of iterations. For details about this parameter, see High-dimensional Sharding APIs.
repeatParams	Input	Parameters that control the operand address strides. They are of the UnaryRepeatParams type (see UnaryRepeatParams), and contain parameters such as the address stride of the operand for the same Data Block between adjacent iterations and the address stride of the operand between different Data Blocks in a single iteration. For details about the address stride of the operand between adjacent iterations, see repeatStride. For details about the address stride of the operand between different data blocks in a single iteration, see dataBlockStride.
count	Input	Number of elements involved in the computation. When setting count, the total memory occupied by the count elements must be 256-byte aligned.

Returns

None

Restrictions

For details about the operand address alignment requirements, see General Address Alignment Restrictions.
If this API is called when the scalar input is a LocalTensor single element, the source operand address cannot overlap with the destination operand address.

dst is arranged in little-endian order as a binary result, with each bit corresponding to the comparison outcome of the respective position in src.
For the APIs that compute the first n pieces of data in a tensor, when setting count, the total memory occupied by the count elements must be 256-byte aligned.
For the Atlas 350 Accelerator Card, int8_t, uint8_t, uint64_t, int64_t, and double data types support only the APIs that compute the first n pieces of data in a tensor. The double data type supports only CMPMODE::EQ.
Either the left or right source operand must be a vector. Currently, the left and right operands cannot be scalars at the same time.
If the scalar input is a LocalTensor single element, idx must be a compile-time constant. If it is a variable, it must be declared as constexpr.

Examples

For an API with a flexible scalar position (before or after a tensor), the scalar input can be an immediate value or a LocalTensor single element.

Example of computing the first n pieces of data of a tensor

        
             // The scalar src1Local[0] is after the tensor.
AscendC::Compares(dstLocal, src0Local, src1Local[0], AscendC::CMPMODE::LT, srcDataSize);

// The scalar src0Local[0] is before the tensor.
static constexpr AscendC::BinaryConfig config = { 0 };
AscendC::Compares<BinaryDefaultType, BinaryDefaultType, true, config>(dstLocal, src0Local[0], src1Local, AscendC::CMPMODE::LT, srcDataSize);

Example of high-dimensional tensor sharding computation (contiguous mask mode)

        
             uint64_t mask = 256 / sizeof(float); // 256 is the number of bytes processed in each iteration.
int repeat = 4;
AscendC::UnaryRepeatParams repeatParams = { 1, 1, 8, 8 };
// repeat = 4, 64 elements one repeat, 256 elements total
// dstBlkStride, srcBlkStride = 1, no gap between blocks in one repeat
// dstRepStride, srcRepStride = 8, no gap between repeats
// The scalar src1Local[0] is after the tensor.
AscendC::Compares(dstLocal, src0Local, src1Local[0], AscendC::CMPMODE::LT, mask, repeat, repeatParams);

// The scalar src0Local[0] is before the tensor.
static constexpr AscendC::BinaryConfig config = { 0 };
AscendC::Compares<BinaryDefaultType, BinaryDefaultType, true, config>(dstLocal, src0Local[0], src1Local, AscendC::CMPMODE::LT, mask, repeat, repeatParams);

Example of high-dimensional tensor sharding computation (bitwise mask mode)

        
             uint64_t mask[2] = { UINT64_MAX, 0};
int repeat = 4;
AscendC::UnaryRepeatParams repeatParams = { 1, 1, 8, 8 };
// repeat = 4, 64 elements one repeat, 256 elements total
// srcBlkStride, = 1, no gap between blocks in one repeat
// dstRepStride, srcRepStride = 8, no gap between repeats
// The scalar src1Local[0] is after the tensor.
AscendC::Compares(dstLocal, src0Local, src1Local[0], AscendC::CMPMODE::LT, mask, repeat, repeatParams);

// The scalar src0Local[0] is before the tensor.
static constexpr AscendC::BinaryConfig config = { 0 };
AscendC::Compares<BinaryDefaultType, BinaryDefaultType, true, config>(dstLocal, src0Local[0], src1Local, AscendC::CMPMODE::LT, mask, repeat, repeatParams);

Parent topic: Comparison and Selection