附录 F Utils API

介绍

此包提供一些常用接口，包括检查接口，日志接口，随机数接口。

主要接口

checkScalar

检查输入的标量 value 与临界值 thres 之间的关系是否满足输入条件 rel，满足则检查成功，否则抛出异常。

/*
 * 检查输入的标量是否有效
 * 参数 value - 需要检查的标量
 * 参数 thres - 临界值
 * 参数 rel - 比较方式，支持的种类有"REL_EQ", "REL_NE", "REL_LT", "REL_LE", "REL_GT", "REL_GE"
 * 参数 argName - 参数名称
 * 参数 primName - 函数名称
 * 异常 ValueException - 当标量无效或输入的比较方式不在支持范围内时，抛出异常
 */
public func checkScalar<T>(value: T, thres: T, rel: String, argName: String, primName: String): Unit where T <: Comparable<T> & ToString

checkScalarRange

检查输入的标量 value 与下限值 lower 和上限值 upper 之间的关系是否满足输入条件 rel，满足则检查成功，否则抛出异常。

/*
 * 检查输入的标量是否在给定的区间
 * 参数 value - 需要检查的标量
 * 参数 lower - 区间的下限
 * 参数 upper - 区间的上限
 * 参数 rel - 比较方式，支持的种类有, "REL_INC_NEITHER", "REL_INC_LEFT", "REL_INC_RIGHT", "REL_INC_BOTH"
 * 参数 argName - 参数名称
 * 参数 primName - 函数名称
 * 异常 ValueException - 当标量无效或输入的比较方式不在支持范围内时，抛出异常
 */
public func checkScalarRange<T>(value: T, lower: T, upper: T, rel: String, argName: String, primName: String): Unit where T <: Comparable<T> & ToString

checkTwoScalar

检查输入的标量 value1 与 value2 之间的关系是否满足输入条件 rel，满足则检查成功，否则抛出异常。与 checkScalar 检查逻辑相同，但如果失败输出的错误信息不同，checkScalar 检查输入与一个已知标量的关系，checkTwoScalar 强调两个变量之间的关系。

/*
 * 检查两个输入的标量是否有效
 * 参数 value1 - 需要检查的第一个标量
 * 参数 value2 - 需要检查的第二个标量
 * 参数 rel - 比较方式，支持的种类有"REL_EQ", "REL_NE", "REL_LT", "REL_LE", "REL_GT", "REL_GE"
 * 参数 arg1Name - 第一个标量的参数名称
 * 参数 arg2Name - 第二个标量的参数名称
 * 参数 primName - 函数名称
 * 异常 ValueException - 当标量无效或输入的比较方式不在支持范围内时，抛出异常
 */
public func checkTwoScalar<T>(value1: T, value2: T, rel: String, arg1Name: String, arg2Name: String, primName: String): Unit where T <: Comparable<T> & ToString

checkStr

检查输入的字符串 str 是否包含在 validTypes 中，包含则检查成功，否则抛出异常。

/*
 * 检查一个字符串输入是否在有效的字符串数组里
 * 参数 str - 需要检查字符串
 * 参数 validTypes - 有效的字符串数组
 * 参数 argName - 参数名称
 * 参数 primName - 函数名称
 * 异常 ValueException - 当字符串无效时，抛出异常
 */
public func checkStr(str: String, validTypes: Array<String>, argName: String, primName: String)

checkBool

检查输入的 value 与 validMode 是否相同，相同则检查成功，否则抛出异常。

/*
 * 检查一个字符串输入是否在有效的字符串数组里
 * 参数 value - 需要检查布尔值
 * 参数 validMode - 有效的布尔值
 * 参数 argName - 参数名称
 * 参数 primName - 函数名称
 * 异常 ValueException - 当布尔值无效时，抛出异常
 */
public func checkBool(value: Bool, validMode: Bool, argName: String, primName: String)

checkArray

检查数组里的每一个元素与输入的临界值 thres 的关系是否都满足 rel，满足则检查成功，否则抛出异常。

/*
 * 检查输入数组中的每一个元素是否有效
 * 参数 arr - 需要检查的数组
 * 参数 thres - 临界值
 * 参数 rel - 比较方式，支持的种类有"REL_EQ", "REL_NE", "REL_LT", "REL_LE", "REL_GT", "REL_GE"
 * 参数 argName - 输入数组的名称
 * 参数 primName - 函数名称
 * 异常 ValueException - 当数组中的元素无效或输入的比较方式不在支持范围内时，抛出异常
 */
public func checkArray<T>(arr: Array<T>, thres: T, rel: String, argName: String, primName: String): Unit where T <: Comparable<T> & ToString

/*
 * 检查输入数组中的每一个元素是否有效
 * 参数 arr - 需要检查的数组
 * 参数 arg2 - 临界值
 * 参数 rel - 比较方式，支持的种类有"REL_EQ", "REL_NE", "REL_LT", "REL_LE", "REL_GT", "REL_GE"
 * 参数 argName - 输入数组的名称
 * 参数 arg2Name - 临界值的名称
 * 参数 primName - 函数名称
 * 异常 ValueException - 当数组中的元素无效或输入的比较方式不在支持范围内时，抛出异常
 */
public func checkArray<T>(arr: Array<T>, arg2: T, rel: String, argName: String, arg2Name: String, primName: String): Unit where T <: Comparable<T> & ToString

/*
 * 检查输入数组中的每一个元素是否有效
 * 参数 arr - 需要检查的数组
 * 参数 thres - 临界值数组
 * 参数 rel - 比较方式，支持的种类有"REL_EQ", "REL_NE", "REL_LT", "REL_LE", "REL_GT", "REL_GE"
 * 参数 arg1Name - 输入数组的名称
 * 参数 arg2Name - 临界值数组的名称
 * 参数 primName - 函数名称
 * 异常 ValueException - 当数组中的元素无效或输入的比较方式不在支持范围内时，抛出异常
 */
public func checkArray<T>(arr: Array<T>, thres: Array<T>, rel: String, arg1Name: String, arg2Name: String, primName: String): Unit where T <: Comparable<T> & ToString

checkArrayRange

检查数组里的每一个元素与下限值 lower 和上限值 upper 之间的关系是否满足输入条件 rel，满足则检查成功，否则抛出异常。

/*
 * 检查输入数组中的每一个元素是否在给定区间
 * 参数 arr - 需要检查的数组
 * 参数 lower - 区间的下限
 * 参数 upper - 区间的上限
 * 参数 rel - 比较方式，支持的种类有，"REL_INC_NEITHER", "REL_INC_LEFT", "REL_INC_RIGHT", "REL_INC_BOTH"
 * 参数 argName - 输入数组的名称
 * 参数 primName - 函数名称
 * 异常 ValueException - 当数组中的元素无效或输入的比较方式不在支持范围内时，抛出异常
 */
public func checkArrayRange<T>(arr: Array<T>, lower: T, upper: T, rel: String, argName: String, primName: String): Unit where T <: Comparable<T> & ToString

checkTensorDtype

检查输入的类型 argType 是否包含在 validTypes 中，包含则检查成功，否则抛出异常。

/*
 * 检查输入 Tensor 的元素类型是否有效
 * 参数 argType - 需要检查的 Tensor 的元素类型
 * 参数 validTypes - 支持的类型数组
 * 参数 argName - Tensor 名称
 * 参数 primName - 函数名称
 * 异常 TypeException - 当元素类型无效时，抛出异常
 */
public func checkTensorDtype(argType: Int32, validTypes: Array<Int32>, argName: String, primName: String)

checkTensorDtypeSame

检查输入的类型 arg1Type 与 arg2Type 是否相同，相同则检查成功，否则抛出异常。

/*
 * 检查两个 Tensor 的元素类型是否相同
 * 参数 arg1Type - 第一个 Tensor 的元素类型
 * 参数 arg2Type - 第二个 Tensor 的元素类型
 * 参数 arg1Name - 第一个 Tensor 的名称
 * 参数 arg1Name - 第二个 Tensor 的名称
 * 参数 primName - 函数名称
 * 异常 TypeException - 当两个 Tensor 的元素类型不同时，抛出异常
 */
public func checkTensorDtypeSame(arg1Type: Int32, arg2Type: Int32, arg1Name: String, arg2Name: String, primName: String)

checkTensorRank

检查输入 value 与输入的临界值 thres 是否满足输入条件 rel。满足则检查成功，否则抛出异常。

/*
 * 检查输入 Tensor 的秩是否正确
 * 参数 value - 需要检查的 Tensor 的秩
 * 参数 thres - 临界值
 * 参数 rel - 比较方式，支持的种类有"REL_EQ", "REL_NE", "REL_LT", "REL_LE", "REL_GT", "REL_GE"
 * 参数 argName - Tensor 的名称
 * 参数 primName - 函数名称
 * 异常 ValueException - 当输入 Tensor 的秩无效或输入的比较方式不在支持范围内时，抛出异常
 */
public func checkTensorRank(value: Int64, thres: Int64, rel: String, argName: String, primName: String)

/*
 * 检查输入 Tensor 的秩是否在给定区间内
 * 参数 size - 需要检查的 Tensor 的秩
 * 参数 lower - 区间的下限
 * 参数 upper - 区间的上限
 * 参数 rel - 比较方式，支持的种类有, "REL_INC_NEITHER", "REL_INC_LEFT", "REL_INC_RIGHT", "REL_INC_BOTH"
 * 参数 argName - Tensor 的名称
 * 参数 primName - 函数名称
 * 异常 ValueException - 当输入 Tensor 的秩无效或输入的比较方式不在支持范围内时，抛出异常
 */
public func checkTensorRank(size: Int64, lower: Int64, upper: Int64, rel: String, argName: String, primName: String)

checkTwoTensorShape

检查输入 arr1 与 arr2 是否相等，相等则检查成功，否则抛出异常。

/*
 * 检查两个 Tensor 的形状是否相等
 * 参数 arr1 - 第一个 Tensor 的形状
 * 参数 arr2 - 第二个 Tensor 的形状
 * 参数 arg1Name - 第一个 Tensor 的名称
 * 参数 arg2Name - 第二个 Tensor 的名称
 * 参数 primName - 函数名称
 * 异常 ValueException - 当两个 Tensor 的形状不等时，抛出异常
 */
public func checkTwoTensorShape(arr1: Array<Int64>, arr2: Array<Int64>, arg1Name: String, arg2Name: String, primName: String)

checkValueDebug

判断 condition 状态，输入 condition 为 true 时，程序继续执行；condition 为 false 时，程序终止，并抛出输入的异常信息 message。只在 CANGJIE_TENSORBOOST_DEBUG 选项打开时生效。

/*
 * 用于实现断言功能，debug模式有效
 * 参数 condition - 判断条件
 * 参数 message - 错误信息
 * 异常 ValueException - 当判断条件为假，抛出异常
 */
public func checkValueDebug(condition: Bool, message: String): Unit

checkValue

判断 condition 状态，输入 condition 为 true 时，程序继续执行；condition 为 false 时，程序终止，并抛出输入的异常信息 message。

/*
 * 实现断言功能，检查数值
 * 参数 condition - 判断条件
 * 参数 message - 错误信息
 * 异常 ValueException - 当判断条件为假，抛出异常
 */
public func checkValue(condition: Bool, message: String): Unit

checkType

判断 condition 状态，输入 condition 为 true 时，程序继续执行；condition 为 false 时，程序终止，并抛出输入的异常信息 message。

/*
 * 实现断言功能，检查类型
 * 参数 condition - 判断条件
 * 参数 message - 错误信息
 * 异常 TypeException - 当判断条件为假，抛出异常
 */
public func checkType(condition: Bool, message: String): Unit

checkRuntime

判断 condition 状态，输入 condition 为 true 时，程序继续执行；condition 为 false 时，程序终止，并抛出输入的异常信息 message。

/*
 * 实现断言功能，检查运行状态
 * 参数 condition - 判断条件
 * 参数 message - 错误信息
 * 异常 RuntimeException - 当判断条件为假，抛出异常
 */
public func checkRuntime(condition: Bool, message: String): Unit

checkOverride

判断 condition 状态，输入 condition 为 true 时，程序继续执行；condition 为 false 时，程序终止，并抛出输入的异常信息 message。

/*
 * 实现断言功能，检查重载
 * 参数 condition - 判断条件
 * 参数 message - 错误信息
 * 异常 NotImplementationException - 当判断条件为假，抛出异常
 */
public func checkOverride(condition: Bool, message: String)

DType 类型

public let UNDEF_DTYPE: Int32 = -1

public let FLOAT32: Int32 = 0

public let FLOAT64: Int32 = 1

public let INT32: Int32 = 2

public let INT64: Int32 = 3

public let UINT8: Int32 = 4

public let UINT16: Int32 = 5

public let UINT32: Int32 = 6

public let BOOL: Int32 = 7

public let STRING: Int32 = 8

public let FLOAT16: Int32 = 9

public let DTYPE_MAP = HashMap<Int32, String>(
    [
        (0, "FLOAT32"),
        (1, "FLOAT64"),
        (2, "INT32"),
        (3, "INT64"),
        (4, "UINT8"),
        (5, "UINT16"),
        (6, "UINT32"),
        (7, "BOOL"),
        (8, "STRING"),
        (9, "FLOAT16")
    ]
)

数据类型 SIZE

定义了不同数据类型的大小

public let BOOL_SIZE: Int64 = 1

public let INT8_SIZE: Int64 = 1

public let UINT8_SIZE: Int64 = 1

public let INT16_SIZE: Int64 = 2

public let UINT16_SIZE: Int64 = 2

public let INT32_SIZE: Int64 = 4

public let UINT32_SIZE: Int64 = 4

public let INT64_SIZE: Int64 = 8

public let UINT64_SIZE: Int64 = 8

public let FLOAT16_SIZE: Int64 = 2

public let FLOAT32_SIZE: Int64 = 4

public let FLOAT64_SIZE: Int64 = 8

enum LogLevel

LogLevel 是表示打印日志等级的枚举类型。

public enum LogLevel {
    | DEBUG         // 调试信息
    | INFO          // 普通信息
    | WARNING       // 告警信息
    | ERROR         // 错误信息
    | EXCEPTION     // 异常信息
}

cjLog

此函数用于打印日志信息

/*
 * 打印日志信息
 * 参数 level - 日志等级
 * 参数 info - 日志信息
 */
public func cjLog(level: LogLevel, info: String)

setSeed

设置全局随机数种子，用在初始化，随机算子中。如果不设置种子，随机正态初始化（RandomNormalInitializer）和随机算子会使用默认种子值 0，其他初始化会随机选择一个种子值。

/*
 * 设置全局随机数种子，用在初始化，随机算子中。如果不设置种子，随机正态初始化（RandomNormalInitializer）和随机算子会使用默认种子值 0，其他初始化会随机选择一个种子值。
 * 参数 seed - 随机数种子
 */
public func setSeed(seed: Int64)

getSeed

此函数用于获取随机数种子

/*
 * 获取全局随机数种子
 * 返回值 Int64 - 随机数种子
 */
public func getSeed(): Int64

getGraphSeed

此函数用于获取图级别的随机数种子

/*
 * 获取图级别的随机数种子。在一个程序中，调用两次设置相同的随机数运算，会生成随机数序列，保证两次随机数运算结果不同同；同时，同样的程序运行两次，结果会和上一次相同。
 * 参数 opSeed - 随机运算的随机数种子
 * 参数 kernelName - 随机运算内核名称
 * 返回值 (Int64, Int64) - 当前图级别种子，算子级种子
 */
public func getGraphSeed(opSeed: Int64, kernelName: String): (Int64, Int64)

TypeException

此类用于抛出类型错误异常

public class TypeException <: Exception {
    public init()
    public init(message: String)
    public override func getClassName(): String
}

ValueException

此类用于抛出数值错误异常

public class ValueException <: Exception {
    public init()
    public init(message: String)
    public override func getClassName(): String
}

RuntimeException

此类用于抛出运行错误异常

public class RuntimeException <: Exception {
    public init()
    public init(message: String)
    public override func getClassName(): String
}

NotImplementationException

此类用于抛出未执行错误异常

public class NotImplementationException <: Exception {
    public init()
    public init(message: String)
    public override func getClassName(): String
}

setSaveGraphs

public func setSaveGraphs(saved: Bool): Unit

函数 setSaveGraphs 用户设置保存计算图功能，当入参是 true 时，启用保存计算图功能，入参是 false 时，则不保存计算图。

如开启保存计算图功能，则网络在运行前向计算时会在当前目录保存 ir 图，即产生后缀名为 .ir 和 .dot 的文件。ir 图的说明见 MindSpore IR 文档。

也可以通过设置环境变量 CANGJIETB_IR_LOG = true，保存仓颉 TensorBoost 计算图; 如果需要更多计算图信息，可以设置环境变量 CANGJIETB_IRPASS_LOG = true，保存优化前后的计算图。

【注意】：该功能仅对静态图模式有效，动态图模式无影响。