(Optional) Generating ES Graph Construction APIs

Prerequisites

• The CANN software package has been installed and the following environment variables have been set. (User root is used as an example, and the CANN software package is installed in the default path.)

  1	source /usr/local/Ascend/cann/set_env.sh

• The following dependencies exist in the environment and the corresponding version requirements have been met:
  • CMake version: later than or equal to 3.17
  • Python 3: later than or equal to 3.7 (required only when add_es_library_and_whl is used)
  • Python dependencies, including wheel (required only when add_es_library_and_whl is used) and setuptools, have been installed.
• The prototype dynamic library has been defined in the CMake file.

  add_library(opgraph_math SHARED)

Modifying the CMake File

1. Import functions.

   # Add the module path so that CMake can find the GenerateEsPackage module.
   list(APPEND CMAKE_MODULE_PATH "/usr/local/Ascend/cann/include/ge/cmake")  
   # Find the module.
   find_package(GenerateEsPackage REQUIRED)

   In the current version, you need to manually add CMAKE_MODULE_PATH to CMakeLists.txt.

2. Generate ES graph construction APIs.
   1. Call add_es_library_and_whl to generate the C/C++ dynamic library or Python wheel package. (The complete products are API carriers.)

      add_es_library_and_whl(
          ES_LINKABLE_AND_ALL_TARGET es_math
          OPP_PROTO_TARGET opgraph_math # The target prototype dynamic library mentioned in Prerequisites
          OUTPUT_PATH       ${CMAKE_BINARY_DIR}/output
      )

   2. Call add_es_library to generate only the C/C++ dynamic library (for C/C++ projects).

      add_es_library(
          ES_LINKABLE_AND_ALL_TARGET es_math
          OPP_PROTO_TARGET  opgraph_math
          OUTPUT_PATH       ${CMAKE_BINARY_DIR}/output
      )

   The add_es_library_and_whl and add_es_library functions are wrappers around the gen_esb binary tool, handling tasks such as compiling source files and compiling and packing the Python .whl package. The binary tool has been integrated into the CANN software package. For details about how to use it, see gen_esb Binary Tool Usage. For details about the parameters in the functions, see Table 1.

   Table 1 Description of CMake file parameters

   Parameter	Required	Description	Example
   ES_LINKABLE_AND_ALL_TARGET	Required	Target name in the products.	es_math and es_nn, es_cv The prefix es_ is recommended, for example, es_math and es_nn. Lowercase letters and underscores (_) are allowed. Special characters and C++ keywords should be avoided.
   OPP_PROTO_TARGET	Required	CMake target name of the operator prototype library. ES APIs are generated for operators in the prototype library.	opgraph_math and opgraph_nn
   OUTPUT_PATH	Required	Root directory of the output products.	${CMAKE_BINARY_DIR}/output
   EXCLUDE_OPS	Optional	Operators to be excluded.	Add and Conv2D

3. Use the generated products.

   # Create an executable file named my_app using the source file main.cpp.
   add_executable(my_app main.cpp)
   # Link the my_app executable file to the es_math target. PRIVATE indicates that the dependency is visible only to my_app.
   target_link_libraries(my_app PRIVATE es_math)

   

   ES graph construction APIs are generated based on the operator IR prototype. Some operator IRs cannot express all the information about an operator (for example, the Conv operator) or the IR expression contains redundant information of an operator (for example, the IdentityN operator). Therefore, you are advised to perform the ES API encapsulation. In this scenario, you can customize ES APIs. For details, see Customizing ES APIs.

The following is an example of a complete CMake file. Replace the Installation path of the CANN software package/usr/local/Ascend/ with the actual one. For more CMake examples, see CMake Examples.

# ===== Basic settings =====
cmake_minimum_required(VERSION 3.17)
project(my_es_project LANGUAGES CXX)

# ===== Import functions (find_package is recommended.) =====
list(APPEND CMAKE_MODULE_PATH "/usr/local/Ascend/cann/include/ge/cmake")
find_package(GenerateEsPackage REQUIRED)

# ===== Part 1: Prerequisites: The prototype library has been defined. =====
add_library(opgraph_math SHARED
)

# ===== Part 2: Generate the ES API package. =====
add_es_library_and_whl(
    ES_LINKABLE_AND_ALL_TARGET es_math
    OPP_PROTO_TARGET  opgraph_math
    OUTPUT_PATH       ${CMAKE_BINARY_DIR}/output
)

# ===== Part 3: Use the generated package in an application. =====
add_executable(my_app
    src/main.cpp
    src/inference.cpp
)

# Link ES_LINKABLE_AND_ALL_TARGET.
target_link_libraries(my_app PRIVATE
    es_math # Automatically obtain the dependencies, header files, and libraries.
)

The build command is as follows:

make my_app
# Output:
# [Smart Build] Step 1: Building internal targets...
# [Smart Build] Found xx generated source file(s)
# [Smart Build] Step 2: Reconfiguring to include generated sources...
# [Smart Build] Step 3: Rebuilding with all generated sources...
# [Smart Build] Successfully built ES package 'es_math' with xx source file(s)
# Built target my_app

Product Description

• The products of add_es_library_and_whl are as follows:

  OUTPUT_PATH/
  ├── include/
  │   └── es_math/               # Header file directory
  │       ├── es_math_ops.h      # C++ API aggregation header file, which contains the graph construction APIs of all operators in es_math.
  │       ├── es_math_ops_c.h    # C API aggregation header file
  │       └── es_Add.h            # Header file of a single operator
  │       └── es_xxx.h            # ES graph construction header file corresponding to other operator prototypes
  ├── lib64/
  │   └── libes_math.so          # Dynamic library
  └── whl/
      └── es_math-1.0.0-py3-none-any.whl  # Python package. You need to manually install this software package when using Python to construct graphs.

• The products of add_es_library are as follows:

  OUTPUT_PATH/
  ├── include/
  │   └── es_math/               # Header file directory
  │       ├── es_math_ops.h      # C++ API aggregation header file
  │       ├── es_math_ops_c.h    # C API aggregation header file
  │       └── es_Add.h           # Header file of a single operator
  │       └── es_xxx.h           # ES graph construction header file corresponding to other operator prototypes
  └── lib64/
  │   └── libes_math.so          # Dynamic library
  └── whl/                        # No .whl package is generated in the C/C++ scenario. This directory is empty.

The naming rules of products are as follows.