Environment Setup

Obtaining ATC

Before model conversion, set up the environment by referring to the CANN Software Installation Guide and ensure that the CANN Toolkit and ops operator package have been installed. (For 8.5.0 and later versions, the installed ops operator package must match the target Ascend AI Processor. Otherwise, the build will fail.) The default installation path of the root user is used as an example. ATC is installed in the /usr/local/Ascend/cann/bin directory.

Setting Environment Variables

The environment variables set using export take effect only in the current window. You can add the relevant commands to the environment variable configuration file (for example, the .bashrc file) as required.
During ATC model conversion, Python libraries required for operator build in ../python/site-packages under the ATC installation directory will be automatically written into the PYTHONPATH environment variable.
If other Python dependencies are imported during operator implementation, add the environment variable PYTHONPATH and configure the path of the imported Python dependencies in the following format:

export PYTHONPATH=xxxx:$PYTHONPATH

Required environment variables
- Set public environment variables.
  After the CANN package is installed, log in to the environment as the CANN operating user and execute the following environment variables:
```
source /usr/local/Ascend/cann/set_env.sh
# If the CANN Toolkit package and ops operator package is installed on a non-Ascend device, the following environment variable must be executed to set the path of the dynamic link library (DLL). Otherwise, skip this step.
export LD_LIBRARY_PATH=/usr/local/Ascend/cann/<arch>-linux/devlib:$LD_LIBRARY_PATH
```
  In the code, /usr/local/Ascend/ is the default installation path of the root user and needs to be replaced with the actual path. Replace <arch> with the actual OS architecture.
- Set Python environment variables.
  Model build requires Python. Take Python 3.7.5 as an example. Run the following command as the CANN running user to set environment variables related to Python 3.7.5:
```
# If multiple Python 3 versions exist in the user environment, specify Python 3.7.5.
export PATH=/usr/local/python3.7.5/bin:$PATH
# Set the library path for Python 3.7.5.
export LD_LIBRARY_PATH=/usr/local/python3.7.5/lib:$LD_LIBRARY_PATH
```
The preceding environment variables take effect only in the current window. You can write the preceding commands to the ~/.bashrc file to make them take effect permanently. The method is as follows:
1. Run the vi ~/.bashrc command in any directory as the installation user and append the preceding commands to the file.
2. Save the file and run the source ~/.bashrc command for the environment variable to take effect.
Optional environment variables
1. Use log flushing, printing to the screen, and redirection.
  - Log flushing:
    During the execution of the atc command, logs are flushed to the following path by default:
    - $HOME/ascend/log/debug/plog/plog-pid_*.log: debug log.
      In the debug log scenario, since the default value of --log is null, no logs about the atc process are generated in the directory. However, other logs may be generated in the directory, for example, logs about Python dependencies. To generate logs about the atc process, set --log to a value other than null.
    - $HOME/ascend/log/run/plog/plog-pid_*.log: run log.
    - $HOME/ascend/log/security/plog/plog-pid_*.log: security log.
    pid indicates the process ID, and * indicates the timestamp when the log file is created.
  - Log printing to the screen:
    During the execution of the atc command, logs are not printed to the screen by default. To print logs to the screen, perform the following operations:
    - Set the environment variable for determining whether to print logs on the screen in the atc command execution window:
```
export ASCEND_SLOG_PRINT_TO_STDOUT=1
```
    - Set the --log option in the atc model conversion command. (This option cannot be set to null.)
    For more information about logs, see Log Reference.
  - Log redirection:
    To redirect logs to files rather than flushing them to a specific directory, set the preceding environment variables for log printing before model conversion and set the --log option (to a value other than null) in the atc command.
```
atc xxx --log=debug >log.txt
```
1. Enable parallel build of operators.
  If the network model to be converted is large, you can set the following environment variable to enable parallel build:
```
export TE_PARALLEL_COMPILER=xx
```
  The value of TE_PARALLEL_COMPILER indicates the number of operator build processes. The value is an integer ranging from 1 to 32, and the default value is 8. A value greater than 1 indicates that the parallel build of operators is enabled. It is recommended that the value be less than or equal to: Number of CPU cores x 80%/Number of Ascend AI Processor. To query the number of Ascend AI Processors, perform the following operation:
  
  Run the npu-smi info -l command in the environment where Ascend AI Processors are installed. Total Count in the command output indicates the number of Ascend AI Processors.
2. Print graph description in each phase of model conversion.
```
export DUMP_GE_GRAPH=1
```
  The preceding environment variable controls the graph dump mode. The values are as follows:
  - 1: dumps all, including the edge relationships and data information.
  - 2: dumps information without data such as weights.
  - 3: dumps only node relationships.
  You can set the following environment variable to control the graphs to dump:
```
export DUMP_GRAPH_LEVEL=2
```
  This environment variable takes effect only when DUMP_GE_GRAPH is enabled. The default value is 2. The following two configuration modes are supported. Both of them are used to control the number of flushed graphs. You can use them as required. Note that the two configuration methods cannot be used together.
  - Set it to a value. Possible values are as follows:
    - 1: dumps graphs in all phases.
    - 2: dumps graphs in the trustlist phase. For details about the trustlisted graphs, see the Trustlist or Not column in Table 1.
    - 3: dumps the last generated graph, that is, the graph optimized and compiled by the GE.
    - 4: dumps the earliest generated graph, that is, the build entry graph provided to the software stack after the GE parses and maps operators. This graph structure has not been compiled or optimized by the GE.
  - Set it to a character string separated by vertical bars (|):
    For example, if this environment variable is set to aa|bb, graphs whose names contain aa and bb are dumped. aa and bb must be valid character strings during graph build. Valid strings can be obtained from a full dump of the graphs.
  After this environment variable is set, the following files are generated in the current path where the atc command is executed.
  - ge_onnx*.pbtxt: model description structure based on ONNX. You can open this file using visualizer software such as Netron.
  - ge_proto*.txt: text file stored in Protobuf format. You can convert it into a JSON file to facilitate fault locating. This file appears in pair with the ge_onnx*.pbtxt file, but has more attributes of the string type than the ge_onnx*.pbtxt file, making the ge_proto*.txt file more comprehensive. You can open either of them.
    Compared with the ge_onnx*.pbtxt file, the ge_proto*.txt file has a smaller size. Therefore, setting DUMP_GE_GRAPH to 2 or 3 has the same effect on the ge_proto*.txt file, that is, dumping information without data such as weights.
  - ge_readable*.txt: (optional) highly readable text file in Dynamo FX graph style. This type of file is generated only when the DUMP_GRAPH_FORMAT environment variable is set and the value contains readable.
  Each of the preceding files corresponds to a step in the model build process. Each file contains all operators involved in this step. For details about dumped graphs, see Dump Graph Details.
3. For more optional environment variables, see Environment Variables.