Power

Applicability

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

Function Usage

Implements element-wise power operations with three types of APIs. The processing logic is as follows:

$\text{[math]}$

$\text{[math]}$

Prototype

Power(dstTensor, src0Tensor, src1Tensor)

Pass the temporary space through the sharedTmpBuffer input parameter.

All or part of the source operand tensors are involved in computation.

template <typename T, bool isReuseSource = false, const PowerConfig& config = defaultPowerConfig>
__aicore__ inline void Power(const LocalTensor<T>& dstTensor, const LocalTensor<T>& src0Tensor, const LocalTensor<T>& src1Tensor, const LocalTensor<uint8_t>& sharedTmpBuffer, uint32_t calCount)

All source operand tensors are involved in computation.

template <typename T, bool isReuseSource = false, const PowerConfig& config = defaultPowerConfig>
__aicore__ inline void Power(const LocalTensor<T>& dstTensor, const LocalTensor<T>& src0Tensor, const LocalTensor<T>& src1Tensor, const LocalTensor<uint8_t>& sharedTmpBuffer)

Allocate the temporary space through the API framework.

All or part of the source operand tensors are involved in computation.

template <typename T, bool isReuseSource = false, const PowerConfig& config = defaultPowerConfig>
__aicore__ inline void Power(const LocalTensor<T>& dstTensor, const LocalTensor<T>& src0Tensor, const LocalTensor<T>& src1Tensor, uint32_t calCount)

All source operand tensors are involved in computation.

template <typename T, bool isReuseSource = false, const PowerConfig& config = defaultPowerConfig>
__aicore__ inline void Power(const LocalTensor<T>& dstTensor, const LocalTensor<T>& src0Tensor, const LocalTensor<T>& src1Tensor)

Power(dstTensor, src0Tensor, src1Scalar)

Pass the temporary space through the sharedTmpBuffer input parameter.

All or part of the source operand tensors are involved in computation.

template <typename T, bool isReuseSource = false, const PowerConfig& config = defaultPowerConfig>
__aicore__ inline void Power(const LocalTensor<T>& dstTensor, const LocalTensor<T>& src0Tensor, const T& src1Scalar, const LocalTensor<uint8_t>& sharedTmpBuffer, uint32_t calCount)

All source operand tensors are involved in computation.

template <typename T, bool isReuseSource = false, const PowerConfig& config = defaultPowerConfig>
__aicore__ inline void Power(const LocalTensor<T>& dstTensor, const LocalTensor<T>& src0Tensor, const T& src1Scalar, const LocalTensor<uint8_t>& sharedTmpBuffer)

Allocate the temporary space through the API framework.

All or part of the source operand tensors are involved in computation.

template <typename T, bool isReuseSource = false, const PowerConfig& config = defaultPowerConfig>
__aicore__ inline void Power(const LocalTensor<T>& dstTensor, const LocalTensor<T>& src0Tensor, const T& src1Scalar, uint32_t calCount)

All source operand tensors are involved in computation.

template <typename T, bool isReuseSource = false, const PowerConfig& config = defaultPowerConfig>
__aicore__ inline void Power(const LocalTensor<T>& dstTensor, const LocalTensor<T>& src0Tensor, const T& src1Scalar)

Power(dstTensor, src0Scalar, src1Tensor)

Pass the temporary space through the sharedTmpBuffer input parameter.

All or part of the source operand tensors are involved in computation.

template <typename T, bool isReuseSource = false, const PowerConfig& config = defaultPowerConfig>
__aicore__ inline void Power(const LocalTensor<T>& dstTensor, const T& src0Scalar, const LocalTensor<T>& src1Tensor, const LocalTensor<uint8_t>& sharedTmpBuffer, uint32_t calCount)

All source operand tensors are involved in computation.

template <typename T, bool isReuseSource = false, const PowerConfig& config = defaultPowerConfig>
__aicore__ inline void Power(const LocalTensor<T>& dstTensor, const T& src0Scalar, const LocalTensor<T>& src1Tensor, const LocalTensor<uint8_t>& sharedTmpBuffer)

Allocate the temporary space through the API framework.

All or part of the source operand tensors are involved in computation.

template <typename T, bool isReuseSource = false, const PowerConfig& config = defaultPowerConfig>
__aicore__ inline void Power(const LocalTensor<T>& dstTensor, const T& src0Scalar, const LocalTensor<T>& src1Tensor, uint32_t calCount)

All source operand tensors are involved in computation.

template <typename T, bool isReuseSource = false, const PowerConfig& config = defaultPowerConfig>
__aicore__ inline void Power(const LocalTensor<T>& dstTensor, const T& src0Scalar, const LocalTensor<T>& src1Tensor)

Due to the complex mathematical computation involved in the internal implementation of this API, additional temporary space is required to store intermediate variables generated during computation. The temporary space can be allocated through the API framework or passed by developers through the sharedTmpBuffer input parameter.

When the API framework is used for temporary space allocation, developers do not need to allocate the space, but must reserve the required size for the space.

When the sharedTmpBuffer input parameter is used for passing the temporary space, the tensor serves as the temporary space. In this case, the API framework is not required for temporary space allocation. This enables developers to manage the sharedTmpBuffer space and reuse the buffer after calling the API, so that the buffer is not repeatedly allocated and deallocated, improving the flexibility and buffer utilization.

If the API framework is used, developers must reserve the temporary space. If sharedTmpBuffer is used, developers must allocate space for sharedTmpBuffer. To obtain the size of the temporary space (BufferSize) to be reserved, use the API provided in GetPowerMaxMinTmpSize.

Parameters

**Table 1** Template parameters
Parameter	Description
T	Data type of the operand. For the Atlas 350 Accelerator Card, the supported data types are uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t, half, bfloat16_t, and float. For the Atlas A3 training product/Atlas A3 inference product, the supported data types are half, float, and int32_t. For the Atlas A2 training product/Atlas A2 inference product, the supported data types are half, float, and int32_t. For the Atlas inference product AI Core, the supported data types are half, float, and int32_t.
isReuseSource	Whether the source operand can be modified. This parameter is reserved. Pass the default value false.
config	Only the Atlas 350 Accelerator Card supports this option. Power computation configuration. This is an optional parameter of the PowerConfig type. The code below describes the definition. algo: Different data types support different Power algorithms. The options are as follows: INTRINSIC (default value): If the data type is an integer, the INTRINSIC algorithm implements Power computation using the fast exponentiation algorithm, supporting the data types uint8_t, int8_t, uint16_t, int16_t, uint32_t, and int32_t. If the data type is floating-point, the INTRINSIC algorithm performs Power computation according to the formula Power(x, y) = exp(y × ln(x)), supporting the data types half and float. DOUBLE_FLOAT_TECH: The DOUBLE_FLOAT_TECH algorithm is a high-precision floating-point algorithm. After the precision of the source operand is improved, Power computation is performed using the formula Power(x, y) = exp(y × ln(x)) to reduce the accuracy drop during computation. The supported data types are half, bfloat16_t, and float.

enum class PowerAlgo {
    INTRINSIC = 0,
    DOUBLE_FLOAT_TECH, 
};

struct PowerConfig {
    PowerAlgo algo = PowerAlgo::INTRINSIC;
};

**Table 2** API parameters
Parameter	Input/Output	Description
dstTensor	Output	Destination operand. The type is LocalTensor, and TPosition can be VECIN, VECCALC, or VECOUT.
src0Tensor	Input	Source operand. The type is LocalTensor, and TPosition can be VECIN, VECCALC, or VECOUT. The source operand must have the same data type as the destination operand.
src1Tensor	Input	Source operand. The type is LocalTensor, and TPosition can be VECIN, VECCALC, or VECOUT. The source operand must have the same data type as the destination operand.
src0Scalar/src1Scalar	Input	Source operand of the Scalar type. The source operand must have the same data type as the destination operand.
sharedTmpBuffer	Input	Temporary memory space. The type is LocalTensor, and TPosition can be VECIN, VECCALC, or VECOUT. For details about how to obtain the temporary space size for the three power APIs with different input data types, see GetPowerMaxMinTmpSize.
calCount	Input	Number of elements involved in the computation.

Returns

None

Restrictions

The source operand address must not overlap the destination operand address.
For the Atlas inference product AI Core, the exponent of the exponentiation operation must be less than 2³¹ – 1.
For details about the operand address alignment requirements, see General Address Alignment Restrictions.

Example

For a complete call example, see Power operator sample.

// dstLocal: tensor for storing the computation result
// srcLocalExp: exponent tensor used for power computation
// srcLocalBase: base tensor used for power computation

// Use srcLocalBase as the base to perform the power operation on all elements in srcLocalExp.
AscendC::Power<T, false>(dstLocal, srcLocalBase, srcLocalExp);

// scalarValueBase: base used for power computation
T scalarValueBase = srcLocalBase.GetValue(0);
// Use the same base scalarValueBase to perform the power operation on all elements in srcLocalExp.
AscendC::Power<T, false>(dstLocal, scalarValueBase, srcLocalExp);

// scalarValueExp: exponent used for power computation
T scalarValueExp = srcLocalExp.GetValue(0);
// Use the same exponent scalarValueExp to perform the power operation on all elements in srcLocalBase.
AscendC::Power<T, false>(dstLocal, srcLocalBase, scalarValueExp);

// static constexpr AscendC::PowerConfig config = { AscendC::PowerAlgo::DOUBLE_FLOAT_TECH };
// AscendC::Power<srcType, false, config>(dstLocal, scalarValue, srcLocal2);

Example data for AscendC::Power<T, false>(dstLocal, srcLocalBase, srcLocalExp):

Input (srcLocalBase): [2 3 4 5 6 7 8 9]
Input (srcLocalExp): [4 3 2 1 4 3 2 1]
Output (dstLocal): [16 27 16 5 1296 343 64 9]

Example data for AscendC::Power<T, false>(dstLocal, scalarValueBase, srcLocalExp):

Input (scalarValueBase): 2
Input (srcLocalExp): [4 3 2 1 4 3 2 1]
Output (dstLocal): [16 8 4 2 16 8 4 2]

Example data for AscendC::Power<T, false>(dstLocal, srcLocalBase, scalarValueExp):

Input (srcLocalBase): [2 3 4 5 6 7 8 9]
Input (scalarValueExp): 4
Output (dstLocal): [16 81 256 625 1296 2401 4096 6561]

Parent topic: Power APIs