# pypto.cast
【免费下载链接】pyptoPyPTO（发音: pai p-t-o）：Parallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto
产品支持情况
| 产品 | 是否支持 |
|---|---|
| Ascend 950PR/Ascend 950DT | √ |
| Atlas A3 训练系列产品/Atlas A3 推理系列产品 | √ |
| Atlas A2 训练系列产品/Atlas A2 推理系列产品 | √ |
功能说明
根据源操作数和目的操作数Tensor的数据类型进行精度转换，如果目的操作数是整型且源操作数的数值超过整型的数据表示范围进行精度转换结果为目的操作数的最大值或者最小值。
注意事项
- PyPTO Tensor 不支持
.to()方法：PyPTO Tensor 没有.to(dtype)方法，必须使用pypto.cast(tensor, dtype)进行数据类型转换
在了解精度转换规则之前，需要先了解浮点数的表示方式和二进制的舍入规则：
浮点数的表示方式
DT_FP16共16bit，包括1bit符号位（S），5bit指数位（E）和10bit尾数位（M）。
当E不全为0或不全为1时，表示的结果为：
(-1)S* 2E - 15* (1 + M)
当E全为0时，表示的结果为：
(-1)S* 2-14* M
当E全为1时，若M全为0，表示的结果为±inf（取决于符号位）；若M不全为0，表示的结果为nan。
上图中S=0，E=15，M = 2-1+ 2-2，表示的结果为1.75。
DT_FP32共32bit，包括1bit符号位（S），8bit指数位（E）和23bit尾数位（M）。
当E不全为0或不全为1时，表示的结果为：
(-1)S* 2E - 127* (1 + M)
当E全为0时，表示的结果为：
(-1)S* 2-126* M
当E全为1时，若M全为0，表示的结果为±inf（取决于符号位）；若M不全为0，表示的结果为nan。
上图中S = 0，E = 127，M = 2-1+ 2-2，最终表示的结果为1.75 。
DT_BF16共16bit，包括1bit符号位（S），8bit指数位（E）和7bit尾数位（M）。
当E不全为0或不全为1时，表示的结果为：
(-1)S* 2E - 127* (1 + M)
当E全为0时，表示的结果为：
(-1)S* 2-126* M
当E全为1时，若M全为0，表示的结果为±inf（取决于符号位）；若M不全为0，表示的结果为nan。
上图中S = 0，E = 127，M = 2-1+ 2-2，最终表示的结果为1.75。
二进制的舍入规则和十进制类似，具体如下：
CAST_RINT模式下，若待舍入部分的第一位为0，则不进位；若第一位为1且后续位不全为0，则进位；若第一位为1且后续位全为0，当M的最后一位为0则不进位，当M的最后一位为1则进位。
CAST_FLOOR模式下，若S为0，则不进位；若S为1，当待舍入部分全为0则不进位，否则，进位。
CAST_CEIL模式下，若S为1，则不进位；若S为0，当待舍入部分全为0则不进位；否则，进位。
CAST_ROUND模式下，若待舍入部分的第一位为0，则不进位；否则，进位。
CAST_TRUNC模式下，总是不进位。
CAST_ODD模式下，若待舍入部分全为0，则不进位；若待舍入部分不全为0，当M的最后一位为1则不进位，当M的最后一位为0则进位。
函数原型
cast(input: Tensor, dtype: DataType, mode: CastMode = CastMode.CAST_NONE, satmode: SaturationMode = SaturationMode.OFF) -> Tensor参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| input | 输入 | 源操作数。 支持的类型为：Tensor。 Tensor支持的数据类型为：DT_FP32，DT_FP16，DT_BF16，DT_INT8，DT_UINT8，DT_INT16，DT_INT32，DT_INT64，DT_INT4，DT_FP8E4M3，DT_FP8E5M2，DT_HF8。 不支持空Tensor；Shape仅支持1-4维；Shape Size不大于2147483647（即INT32_MAX）。 |
| dtype | 输入 | 精度转换后的数据类型。 支持的数据类型为：DT_FP32，DT_FP16，DT_BF16，DT_INT8，DT_UINT8，DT_INT16，DT_INT32，DT_INT64，DT_INT4，DT_FP8E4M3，DT_FP8E5M2，DT_HF8。 |
| CastMode | 输入 | 源操作数枚举类型，用以控制精度转换处理模式，具体定义为：CastMode 。 默认为 CAST_NONE，常见类型之间的转换，框架会自动转换，与torch对齐，详见约束说明。 |
| SaturationMode | 输入 | 饱和模式枚举类型，用以控制浮点数转整数时的溢出处理方式，具体定义为：SaturationMode 。 默认为 OFF（截断模式），当设置为 ON 时，超出目标类型范围的数值会被截断到最大值或最小值（饱和截断），详见约束说明。 |
约束说明
A2A3 架构支持的转换：
源类型 目标类型 饱和模式设置 默认CastMode 特殊说明 DT_FP16 DT_FP32 - - - DT_FP16 DT_INT32 - CAST_TRUNC - DT_FP16 DT_INT16 √ CAST_TRUNC 支持 inf/-inf 等边缘情况 DT_FP16 DT_INT8 √ CAST_TRUNC 支持 inf/-inf 等边缘情况 DT_FP16 DT_UINT8 √ CAST_TRUNC - DT_FP16 DT_INT4 - - 打包类型，每字节包含2个元素 DT_BF16 DT_FP32 - - - DT_BF16 DT_INT32 - CAST_TRUNC - DT_INT32 DT_FP32 - - - DT_INT32 DT_INT16 √ - - DT_INT32 DT_INT64 - - - DT_INT32 DT_FP16 - - deq 模式 DT_FP32 DT_BF16 - CAST_RINT - DT_FP32 DT_FP16 - CAST_RINT - DT_FP32 DT_INT16 √ CAST_TRUNC 支持 inf/-inf 等边缘情况 DT_FP32 DT_INT32 - CAST_TRUNC - DT_FP32 DT_INT64 - CAST_TRUNC - DT_UINT8 DT_FP16 - - - DT_INT8 DT_FP16 - - - DT_INT16 DT_FP32 - - - DT_INT16 DT_FP16 - - - DT_INT64 DT_FP32 - CAST_RINT - DT_INT64 DT_INT32 √ - - DT_INT4 DT_FP16 - - 打包类型，每字节包含2个元素 Ascend 950PR/Ascend 950DT (A5 架构) 支持的转换：
源类型 目标类型 饱和模式设置 默认CastMode 特殊说明 DT_FP32 DT_FP16 - CAST_RINT - DT_FP32 DT_BF16 - CAST_RINT - DT_FP32 DT_INT16 √ CAST_TRUNC 支持 inf/-inf 等边缘情况 DT_FP32 DT_INT32 - CAST_TRUNC - DT_FP32 DT_INT64 - CAST_TRUNC - DT_FP32 DT_FP8E4M3 - CAST_RINT - DT_FP32 DT_FP8E5M2 - CAST_RINT - DT_FP32 DT_HF8 - CAST_ROUND 特殊舍入模式 DT_FP16 DT_FP32 - - - DT_FP16 DT_INT32 - CAST_TRUNC - DT_FP16 DT_INT16 √ CAST_TRUNC 支持 inf/-inf 等边缘情况 DT_FP16 DT_INT8 √ CAST_TRUNC 支持 inf/-inf 等边缘情况 DT_FP16 DT_UINT8 √ CAST_TRUNC - DT_FP16 DT_HF8 - CAST_ROUND 特殊舍入模式 DT_BF16 DT_FP32 - - - DT_BF16 DT_INT32 - CAST_TRUNC - DT_BF16 DT_FP16 - - - DT_UINT8 DT_FP16 - - - DT_UINT8 DT_UINT16 - - - DT_UINT8 DT_INT16 - - - DT_UINT8 DT_INT32 - - - DT_INT8 DT_FP16 - - - DT_INT8 DT_UINT16 - - - DT_INT8 DT_INT16 - - - DT_INT8 DT_INT32 - - - DT_INT16 DT_UINT8 - - - DT_INT16 DT_FP16 - - - DT_INT16 DT_FP32 - - - DT_INT16 DT_UINT32 - - - DT_INT16 DT_INT32 - - - DT_INT32 DT_FP32 - - - DT_INT32 DT_INT16 √ - - DT_INT32 DT_UINT16 - - - DT_INT32 DT_INT64 - - - DT_INT32 DT_UINT8 - - - DT_INT32 DT_FP16 - - - DT_UINT32 DT_UINT8 - - - DT_UINT32 DT_UINT16 - - - DT_UINT32 DT_INT16 - - - DT_INT64 DT_FP32 - CAST_RINT - DT_INT64 DT_INT32 √ - - DT_FP8E4M3 DT_FP32 - - - DT_FP8E5M2 DT_FP32 - - - DT_HF8 DT_FP32 - - - 饱和模式设置说明：
- FP16→UINT8、FP16→INT8、FP32→INT16、FP16→INT16、INT64→INT32、INT32→INT16 转换默认使用 OFF模式（截断/回绕），以保持PyTorch兼容性; 当cast用于量化场景或有其他需求时，上述6种转换场景用户可以根据需要设置为ON模式（饱和）。
- 其他转换该字段设置无效。
当 cast 前后类型相同的时候，某些场景下会产生空操作，不保证精度。
特殊说明：
- DT_INT4（S4）是一种打包类型，每字节包含2个元素
- 支持多种舍入模式：RINT、ROUND、FLOOR、CEIL、TRUNC、ODD、NONE
- 提供 PyTorch 兼容模式，处理 inf/-inf 等边缘情况
- 支持 int32→half 的 deq 模式转换
- A5 架构支持 FP8 系列类型（DT_FP8E4M3、DT_FP8E5M2、DT_HF8）的转换
- A5 架构中 DT_HF8 (hifloat8) 类型需要使用特殊的 CAST_ROUND 舍入模式
调用示例
TileShape设置示例
调用该operation接口前，应通过set_vec_tile_shapes设置TileShape。
TileShape维度应和输出一致。
如输入input shape为[m, n]，输出为[m, n]，TileShape设置为[m1, n1]，则m1, n1分别用于切分m, n轴。
pypto.set_vec_tile_shapes(4, 16)接口调用示例
x = pypto.tensor([2], pypto.DT_FP32) y = pypto.cast(x, pypto.DT_FP16)结果示例如下：
输入数据x: [2.0, 3.0] # x.dtype: pypto.DT_FP32 输出数据y: [2.0, 3.0] # y.dtype: pypto.DT_FP16使用饱和模式（推荐用于浮点数转整数）
# 示例 1：FP16 转 INT8，使用饱和模式防止溢出 x = pypto.tensor([300.0, -300.0, 50.0], pypto.DT_FP16) y = pypto.cast(x, pypto.DT_INT8, satmode=pypto.SaturationMode.ON) # 输出：[127, -128, 50] # 示例 2：FP16 转 INT8，使用饱和模式防止溢出 x = pypto.tensor([300.0, -300.0, 50.0], pypto.DT_FP16) y = pypto.cast(x, pypto.DT_INT8, satmode=pypto.SaturationMode.OFF) # 输出：[44, -44, 50]【免费下载链接】pyptoPyPTO（发音: pai p-t-o）：Parallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
