Sqrt
产品支持情况
不传入config的原型
- Ascend 950PR/Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品AI Core：支持
- Atlas 推理系列产品Vector Core：不支持
- Atlas 训练系列产品：支持
- Kirin X90：支持
- Kirin 9030：支持
传入config的原型
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品AI Core：不支持
- Atlas 推理系列产品Vector Core：不支持
- Atlas 训练系列产品：不支持
- Kirin X90：不支持
- Kirin 9030：不支持
功能说明
头文件路径为："basic_api/kernel_operator_vec_unary_intf.h"。
Sqrt属于单目矢量类计算接口，负责将输入的tensor按元素做开方。计算公式如下：
函数原型
传入config的原型
tensor前n个数据连续计算
C++template <typename T, const SqrtConfig& config = DEFAULT_SQRT_CONFIG> __aicore__ inline void Sqrt(const LocalTensor<T>& dst, const LocalTensor<T>& src, const int32_t& count)tensor高维切分计算
mask逐bit模式
C++template <typename T, bool isSetMask = true, const SqrtConfig& config = DEFAULT_SQRT_CONFIG> __aicore__ inline void Sqrt(const LocalTensor<T>& dst, const LocalTensor<T>& src, uint64_t mask[], const uint8_t repeatTime, const UnaryRepeatParams& repeatParams)mask连续模式
C++template <typename T, bool isSetMask = true, const SqrtConfig& config = DEFAULT_SQRT_CONFIG> __aicore__ inline void Sqrt(const LocalTensor<T>& dst, const LocalTensor<T>& src, uint64_t mask, const uint8_t repeatTime, const UnaryRepeatParams& repeatParams)
不传入config的原型
tensor前n个数据连续计算
C++template <typename T> __aicore__ inline void Sqrt(const LocalTensor<T>& dst, const LocalTensor<T>& src, const int32_t& count)tensor高维切分计算
mask逐bit模式
C++template <typename T, bool isSetMask = true> __aicore__ inline void Sqrt(const LocalTensor<T>& dst, const LocalTensor<T>& src, uint64_t mask[], const uint8_t repeatTime, const UnaryRepeatParams& repeatParams)mask连续模式
C++template <typename T, bool isSetMask = true> __aicore__ inline void Sqrt(const LocalTensor<T>& dst, const LocalTensor<T>& src, uint64_t mask, const uint8_t repeatTime, const UnaryRepeatParams& repeatParams)
参数说明
表1 模板参数说明
| 参数名 | 描述 |
|---|---|
| T | 操作数数据类型。 |
| isSetMask | 是否在接口内部设置mask。 • true，表示在接口内部设置mask。 • false，表示在接口外部设置mask，开发者需要使用SetVectorMask接口设置mask值。这种模式下，接口入参中的mask值设置为占位符 MASK_PLACEHOLDER，用于占位，无实际含义。 |
| config | 该参数仅支持Ascend 950PR/Ascend 950DT。 用于配置精度计算模式，SqrtConfig类型，定义如下： enum class SqrtAlgo {通过SqrtConfig结构体的参数algo来配置精度计算模式。algo取值如下：• SqrtAlgo::INTRINSIC、SqrtAlgo::PRECISION_1ULP_FTZ_TRUE，使用单指令计算得出结果，最大精度误差为1ulp。 • SqrtAlgo::FAST_INVERSE、SqrtAlgo::PRECISION_0ULP_FTZ_FALSE，使用快速求逆算法得出结果。适用于输入值在[0, 85070596800837026223494223584045301760]范围内的计算。在该范围内，算法保证输出的最大精度误差为0ulp；当输入值大于85070596800837026223494223584045301760时，输出为0。目前，该算法仅支持float数据类型，并在该模式下支持Subnormal数据计算。 • SqrtAlgo::PRECISION_1ULP_FTZ_FALSE，仅支持half类型的Subnormal数据计算，此时最大精度误差为1ulp。 该参数的默认值DEFAULT_SQRT_CONFIG的取值如下： constexpr SqrtConfig DEFAULT_SQRT_CONFIG = { SqrtAlgo::INTRINSIC };调用本原型时若不显式传入config参数，则默认使用DEFAULT_SQRT_CONFIG，此时行为与不传入config参数的原型等价。 |
表2 参数说明
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| dst | 输出 | 目的操作数。 类型为LocalTensor，支持的TPosition为VECIN/VECCALC/VECOUT。 地址对齐约束参考通用地址对齐约束。 |
| src | 输入 | 源操作数。 类型为LocalTensor，支持的TPosition为VECIN/VECCALC/VECOUT。 地址对齐约束参考通用地址对齐约束。 |
| count | 输入 | 参与计算的元素个数。关于该参数的具体说明请参考连续计算。 |
| mask[]/mask | 输入 | mask用于控制每次迭代内参与计算的元素。详细设置参考掩码。 |
| repeatTime | 输入 | 重复迭代次数。矢量计算单元，每次读取连续的256Bytes数据进行计算，为完成对输入数据的处理，必须通过多次迭代（repeat）才能完成所有数据的读取与计算。repeatTime表示迭代的次数。 关于该参数的具体说明请参考高维切分。 |
| repeatParams | 输入 | 控制操作数地址步长的参数。UnaryRepeatParams类型，包含操作数相邻迭代间相同DataBlock的地址步长，操作数同一迭代内不同DataBlock的地址步长等参数。 相邻迭代间的地址步长参数说明请参考repeatStride；同一迭代内DataBlock的地址步长参数说明请参考dataBlockStride。 |
数据类型
T支持的数据类型为：half、float。
返回值说明
无
约束说明
- 当参数count或repeatTime取值为0时，该接口的行为如下：
- 针对如下型号，当参数count或repeatTime取值为0时，不会执行计算操作，不会对目的操作数进行写入，该接口将被视为NOP（空操作）。
- Atlas A3 训练系列产品/Atlas A3 推理系列产品
- Atlas A2 训练系列产品/Atlas A2 推理系列产品
- 针对Ascend 950PR/Ascend 950DT：该接口通过VF调用Reg矢量计算API实现兼容，当参数count或repeatTime取值为0时，软仿行为不保证该接口被视为NOP（空操作）。
- 针对如下型号，当参数count或repeatTime取值为0时，不会执行计算操作，不会对目的操作数进行写入，该接口将被视为NOP（空操作）。
- 对UB空间的占用说明。针对Ascend 950PR/Ascend 950DT：
- tensor高维切分计算占用8KB Unified Buffer。
- tensor前n个数据连续计算不涉及8KB Unified Buffer的占用。
- 针对Ascend 950PR/Ascend 950DT，SqrtAlgo::FAST_INVERSE、SqrtAlgo::PRECISION_0ULP_FTZ_FALSE，使用快速求逆算法得出结果。适用于输入值在[0, 85070596800837026223494223584045301760]范围内的计算。在该范围内，算法保证输出的最大精度误差为0ulp；当输入值大于85070596800837026223494223584045301760时，输出为0。目前，该算法仅支持float数据类型，并在该模式下支持Subnormal数据计算。
- 如果src中的数值为非正数，可能会产生未知结果。
关键特性
针对Ascend 950PR/Ascend 950DT，有如下关键特性：
最大精度误差：
- SqrtAlgo::INTRINSIC、SqrtAlgo::PRECISION_1ULP_FTZ_TRUE，最大精度误差为1ulp。
- SqrtAlgo::PRECISION_1ULP_FTZ_FALSE，软仿实现，最大精度误差为1ulp。
- SqrtAlgo::FAST_INVERSE、SqrtAlgo::PRECISION_0ULP_FTZ_FALSE，软仿实现，最大精度误差为0ulp。
配置Subnormal模式：
FTZ（Flush To Zero）：一种浮点运算模式，当结果为Subnormal时，将其直接清零（近似为0），而非保留其精确的微小数值。
只有将algo设置为SqrtAlgo::FAST_INVERSE、SqrtAlgo::PRECISION_0ULP_FTZ_FALSE、SqrtAlgo::PRECISION_1ULP_FTZ_false时，Sqrt接口才会保留并正确输出Subnormal结果；其他模式下Subnormal均被FTZ。
由于Subnormal的计算行为是通过软件仿真算法实现，一般场景推荐使用性能更好的SqrtAlgo::INTRINSIC、SqrtAlgo::PRECISION_1ULP_FTZ_TRUE；需要精确Subnormal输出的场景（如特定数据精度要求的算法、避免除零错误）使用SqrtAlgo::FAST_INVERSE、SqrtAlgo::PRECISION_0ULP_FTZ_FALSE、SqrtAlgo::PRECISION_1ULP_FTZ_FALSE。
调用示例
tensor高维切分计算样例-mask连续模式
C++uint64_t mask = 256 / sizeof(half); // repeatTime = 4, 128 elements one repeat, 512 elements total. // dstBlkStride, srcBlkStride = 1, no gap between blocks in one repeat. // dstRepStride, srcRepStride = 8, no gap between repeats. AscendC::Sqrt(dstLocal, srcLocal, mask, 4, { 1, 1, 8, 8 });tensor高维切分计算样例-mask逐bit模式
C++uint64_t mask[2] = { UINT64_MAX, UINT64_MAX }; // repeatTime = 4, 128 elements one repeat, 512 elements total. // dstBlkStride, srcBlkStride = 1, no gap between blocks in one repeat. // dstRepStride, srcRepStride = 8, no gap between repeats. AscendC::Sqrt(dstLocal, srcLocal, mask, 4, { 1, 1, 8, 8 });tensor前n个数据计算接口样例
C++AscendC::Sqrt(dstLocal, srcLocal, 512);以下示例仅支持Ascend 950PR/Ascend 950DT
C++static constexpr SqrtConfig config = { SqrtAlgo::PRECISION_1ULP_FTZ_FALSE }; AscendC::Sqrt<T, config>(dstLocal, srcLocal, 512);
结果示例如下：
Bash
输入数据srcLocal：[1.0 2.0 3.0 4.0 ...]
输出数据dstLocal：[1.0 1.414 1.732 2.0 ...]