算子调用

说明：本项目可调用的算子参见算子列表，算子对应aclnn接口参见aclnn列表。

前提条件

环境部署：调用项目算子之前，请先参考环境部署完成基础环境搭建。
调用算子列表：项目可调用的算子参见算子列表，算子对应的aclnn接口参见aclnn列表。

编译执行

基于社区版CANN包对算子源码修改时，可采用如下方式进行源码编译：

自定义算子包：选择部分算子编译生成的包称为自定义算子包，以挂载形式作用于CANN包，不改变原始包内容。生成的自定义算子包优先级高于原始CANN包。该包支持aclnn方式和图模式调用算子。
ops-math包：选择整个项目编译生成的包称为ops-math包，可完整替换CANN包对应部分。该包支持aclnn方式和图模式调用算子。

自定义算子包

编译自定义算子包

进入项目根目录，执行如下编译命令：
```
bash build.sh --pkg --soc=${soc_version} [--vendor_name=${vendor_name}] [--ops=${op_list}]
# 以Abs算子编译为例
# bash build.sh --pkg --soc=ascend910b --ops=abs
# 编译experimental贡献目录下的用户算子
# bash build.sh --pkg --experimental --soc=ascend910b --ops=abs
```
- --soc：${soc_version}表示NPU型号。Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件使用"ascend910b"（默认），Atlas A3 训练系列产品/Atlas A3 推理系列产品使用"ascend910_93"。
- --vendor_name（可选）：${vendor_name}表示构建的自定义算子包名，默认名为custom。
- --ops（可选）：${op_list}表示待编译算子，不指定时默认编译所有算子。格式形如"abs,add_lora,..."，多算子之间用英文逗号","分隔。
- --experimental（可选）：表示编译用户保存在experimental贡献目录下的算子。
说明：若${vendor_name}和${op_list}都不传入编译的是ops-math包；若编译所有算子的自定义算子包，需传入${vendor_name}。

若提示如下信息，说明编译成功。
```
Self-extractable archive "cann-ops-math-${vendor_name}_linux-${arch}.run" successfully created.
```
编译成功后，run包存放于项目根目录的build_out目录下。
安装自定义算子包
```
./build_out/cann-ops-math-${vendor_name}_linux-${arch}.run
```
自定义算子包安装路径为${ASCEND_HOME_PATH}/vendors，${ASCEND_HOME_PATH}已通过环境变量配置，表示CANN toolkit包安装路径，一般为${install_path}/cann。
（可选）删除自定义算子包

注意自定义算子包不支持卸载，可通过如下操作删除：

请删除vendors/${vendor_name}目录，并删除vendors/config.ini中load_priority对应${vendor_name}的配置项。

ops-math包

编译ops-math包

进入项目根目录，执行如下编译命令：
```
# 编译除experimental目录外的所有算子
bash build.sh --pkg [--jit] --soc=${soc_version}
# 编译experimental目录下的所有算子
# bash build.sh --pkg --experimental [--jit] --soc=${soc_version}
```
- --jit（可选）：设置后表示不编译算子二进制文件，如需使用aclnn调用算子，该选项无需设置。
- --soc：${soc_version}表示NPU型号。Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件使用"ascend910b"（默认），Atlas A3 训练系列产品/Atlas A3 推理系列产品使用"ascend910_93"。
- --experimental（可选）：表示编译用户保存在experimental目录下的算子。
若提示如下信息，说明编译成功。
```
Self-extractable archive "cann-${soc_name}-ops-math_${cann_version}_linux-${arch}.run" successfully created.
```
${soc_name}表示NPU型号名称，即${soc_version}删除“ascend”后剩余的内容。编译成功后，run包存放于build_out目录下。
安装ops-math包
```
# 安装命令
./build_out/cann-${soc_name}-ops-math_${cann_version}_linux-${arch}.run --full --install-path=${install_path}
```
${install_path}：表示指定安装路径，需要与toolkit包安装在相同路径，默认安装在/usr/local/Ascend目录。

（可选）卸载ops-math包

# 卸载命令
./${install_path}/cann/share/info/ops_math/script/uninstall.sh

一键式工具执行

上述操作也可以通过一键式工具脚本执行，具体操作参考一键式工具命令行说明

本地验证

通过项目根目录build.sh脚本，可快速调用算子和UT用例，验证项目功能是否正常，build参数介绍参见build参数说明。

执行算子样例
- 完成自定义算子包安装后，执行命令如下：
```
bash build.sh --run_example ${op} ${mode} ${pkg_mode} [--vendor_name=${vendor_name}]
# 以Abs算子example执行为例
# bash build.sh --run_example abs eager cust --vendor_name=custom
```
  - ${op}：表示待执行算子，算子名小写下划线形式，如abs。
  - ${mode}：表示执行模式，目前支持eager（aclnn调用）、graph（图模式调用）。
  - ${pkg_mode}：表示包模式，目前仅支持cust，即自定义算子包。
  - ${vendor_name}（可选）：与构建的自定义算子包设置一致，默认名为custom。
  说明：${mode}为graph时，不指定${pkg_mode}和${vendor_name}
- 完成ops-math包安装后，执行命令如下：
```
bash build.sh --run_example ${op} ${mode}
# 以Abs算子example执行为例
# bash build.sh --run_example abs eager
```
  - ${op}：表示待执行算子，算子名小写下划线形式，如abs。
  - ${mode}：表示算子执行模式，目前支持eager（aclnn调用）、graph（图模式调用）。
执行算子样例后会打印执行结果，以Abs算子为例，结果如下：
```
abs result[0] is: 1.000000
abs result[1] is: 1.000000
abs result[2] is: 1.000000
abs result[3] is: 2.000000
abs result[4] is: 2.000000
abs result[5] is: 2.000000
abs result[6] is: 3.000000
abs result[7] is: 3.000000
```

执行算子UT

说明：执行UT用例依赖googletest单元测试框架，详细介绍参见googletest官网。

# 安装根目录下test相关requirements.txt依赖
pip3 install -r tests/requirements.txt
# 方式1: 编译并执行指定算子和对应功能的UT测试用例（选其一）
bash build.sh -u --[opapi|ophost|opkernel] --ops=abs
# 方式2: 编译并执行所有的UT测试用例
# bash build.sh -u
# 方式3: 编译所有的UT测试用例但不执行
# bash build.sh -u --noexec
# 方式4: 编译并执行对应功能的UT测试用例（选其一）
# bash build.sh -u --[opapi|ophost|opkernel]
# 方式5: 编译对应功能的UT测试用例但不执行（选其一）
# bash build.sh -u --noexec --[opapi|ophost|opkernel]

假设验证ophost功能是否正常，执行如下命令：

bash build.sh -u --ophost

执行完成后出现如下内容，表示执行成功。

Global Environment TearDown
[==========] ${n} tests from ${m} test suites ran. (${x} ms total)
[  PASSED  ] ${n} tests.
[100%] Built target math_op_host_ut

${n}表示执行了n个用例，${m}表示m项测试，${x}表示执行用例消耗的时间，单位为毫秒。