Function: init

C Prototype	*aclError aclInit(const char configPath)**
Python Function	ret = acl.init(config_path)
Function Usage	pyACL initialization function.
Input Description	config_path: str, path of the configuration file, including the file name. The configuration file is in JSON format. A JSON file allows up to 10 levels of curly brackets and square brackets, respectively. To use the default configurations, directly call the acl.init interface without passing any parameter or set the configuration file to an empty JSON string (that is, only {} exists in the configuration file). The configuration file is in JSON format. The following configurations are supported: Dump information configuration, including: Model dump configuration (used to export the input and output data of operators at each layer in the model) and single-operator dump configuration (used to export the input and output data of an operator). The exported data is used to compare with that of a specified model or operator to locate accuracy issues. For details about the configuration example, description, and restrictions, see Configuration File Example (for Model Dump and Single-Operator Dump). Dump is disabled by default. Dump configuration of the exception operator (used to export the input and output data, workspace information, and tiling information of the exception operator). The exported data is used to analyze AI Core errors. For details about the configuration example, see Configuration File Example (Exception Operator Dump Configuration). Dump is disabled by default. Dump configuration of the overflow/underflow operator (used to export the input and output data of the overflow/underflow operator in the model). The exported data is used to analyze overflow/underflow causes and locate model accuracy problems. For details about the configuration example, description, and restrictions, see Example Configuration (Overflow/Underflow Operator Dump). Dump is disabled by default. Profiling configuration. For the configuration example, description, and restrictions, see Profiling Instructions. Profiling is disabled by default. Operator cache aging configuration. To save memory and balance the calling performance, you can use the max_opqueue_num parameter to configure the maximum length of the "operator type and single-operator model" mapping queue. If the length of the mapping queue reaches the maximum, the least used mapping information and single-operator models in the cache are deleted before the most recent mapping information and the corresponding single-operator model are loaded. The default maximum length of the mapping queue is 20000. For details about the configuration example and restrictions, see Example Configuration (Operator Cache Information Aging). Error information report mode configuration, which is used to control the acl.get_recent_err_msg API to obtain error information by process or thread level. By default, error information is obtained by thread level. For details about the example, see Configuration File Example (Configuration of Error Information Reporting Mode). Dump configuration and profiling configuration should not be both set. The dump operation could affect the system performance, resulting in inaccurate profile data collected by Profiling.
Return Value	ret: int, error code. 0 indicates success. Other values indicate failure.
Restrictions	The acl.init API can be called only once in a process and is used together with the acl.finalize deinitialization API. acl.init must be called before app development using pyACL APIs. Otherwise, an error may occur during the initialization of internal system resources, causing other service exceptions.
API	pyACL provides more flexible APIs for enabling Dump and Profiling. Unlike acl.init, these APIs can be called repeatedly in a process, allowing for varied dump/profiling configurations with each call. Obtain dump data. For details, see acl.mdl.init_dump, acl.mdl.set_dump, and acl.mdl.finalize_dump. Obtain profile data. For details, see Profile Data Collection.
Reference	For the API call example, see Initializing pyACL.

Configuration File Example (for Model Dump and Single-Operator Dump)

Model dump configuration example:

{                                                                                            
	"dump":{
		"dump_list":[                                                                        
			{	"model_name":"ResNet-101"
			},
			{                                                                                
				"model_name":"ResNet-50",
				"layer":[
				      "conv1conv1_relu",
				      "res2a_branch2ares2a_branch2a_relu",
				      "res2a_branch1",
				      "pool1"
				] 
			}  
		],  
		"dump_path":"$HOME/output",
                "dump_mode":"output",
		"dump_op_switch":"off",
                "dump_data":"tensor"
	}                                                                                        
}

Single-operator dump configuration:

{
    "dump":{
        "dump_path":"output",
        "dump_list":[], 
	"dump_op_switch":"on",
        "dump_data":"tensor"
    }
}

**Table 1** Format of the **acl.json** file
Parameter	Description	Note
dump	-	For TBE and AI CPU operators that do not output results, (for example, StreamActive, Send, Recv, and const), dump data is not generated. For operators that are not executed on AI CPU or AI Core (for example, concatD) after build, dump data cannot be generated. If only certain operators are to be dumped, since the Data operators are not executed on AI CPU or AI Core, you need to select all the downstream operators of the Data operator.
dump_list	(Required) List of network-wide models for data dump. Create model dump configuration information. If multiple models need to be dumped, separate them with commas (,). In the single-operator execution scenario, dump_list is empty.	-
model_name	Model name. To load a model from a file, enter the model file name without the name extension. You can also set this parameter to the value of the outermost name field in the .json file after ATC-based model conversion. To load a model from memory, set this parameter to the value of the name field in the .json file after ATC-based model conversion.	Ensure that each model_name is unique. A model can be loaded from the memory or a file. Assume that a model is loaded from a file and this parameter is set to the value of the outermost name field in the .json file after ATC-based model conversion. If the model_name configuration item in the acl.json file contains two values: model file name and the value of name obtained here, the model file name takes effect.
layer	Operator name. The value can be the name of the operator after ATC model conversion or the name of the original operator before conversion. To dump certain operators, configure each operator in a line in the layer field and separate them with commas (,). If the input of the specified operator involves the data operator, the data operator information is also dumped. To dump all operators of a model, the layer field does not need to be included. If you do not set model_name, the operators of all models are dumped by default. If model_name is set, the corresponding operators of the model are dumped.	It is advised to dump certain operators only. Otherwise, excessive data may induce timeouts if the I/O performance is poor.
dump_path	(Required) Dump path in the operating environment. The path can be either absolute or relative. An absolute path starts with a slash (/), for example, $HOME/output. A relative path starts with a directory name, for example, output.	The directory specified by this parameter must be created in advance and the user configured during installation must have the read and write permissions on the directory.
dump_mode	Dump mode. input: dumps operator inputs. output (default): dumps operator outputs. all: dumps both operator inputs and outputs.	-
dump_op_switch	Dump switch of a single-operator model. on: enables dump for the single-operator model. off (default): disables dump for the single-operator model.	-
dump_step	Iterations to dump. This parameter is not required in the inference scenario. If this parameter is not configured, dump data will be generated for all iterations by default, which may result in a large amount of data. You are advised to specify iterations as required. Separate multiple iterations using vertical bars (\|), for example, 0\|5\|10. You can also use hyphens (-) to specify the iteration range, for example, 0\|3-5\|10. Configuration example: { "dump":{ "dump_list":[ ...... ], "dump_path":"$HOME/output", "dump_mode":"output", "dump_op_switch":"off" "dump_step": "0\|3-5\|10" } }	-
dump_data	Type of operator content to dump. tensor (default): dumps operator data. stats: dumps operator statistics. The result file is in .csv format and contains the operator name, input/output data type, maximum value, and minimum value. Dumping a large amount of data typically requires a significant amount of time. One solution is to first dump operator statistics, use the statistics to identify potentially abnormal operators, and then proceed to dump the data of the identified operators. In the model dump scenario, the information of operator input or output or both can be collected based on the configuration of dump_mode.	-

Configuration File Example (Exception Operator Dump Configuration)

Set dump_scene to lite_exception to enable the dump function of the exception operator. In addition, you can use the ASCEND_WORK_PATH environment variable to configure the dump path. Otherwise, the data is dumped to the current execution directory of the app.

The following gives a configuration example:

{
   "dump":{
           "dump_scene":"lite_exception"
    }
}

The dump configuration of the abnormal operator cannot be enabled together with the model dump configuration or single-operator dump configuration. Otherwise, the model dump or single-operator dump does not take effect.

Example Configuration (Overflow/Underflow Operator Dump)

Restrictions:

If dump_debug is set to on, overflow/underflow operator configuration is enabled. If dump_debug is not set or is set to off, this function is disabled.
If this function is enabled, dump_path must be set, indicating the directory for storing exported data files.
The path can be either absolute or relative.
- An absolute path starts with a slash (/), for example, /home.
- A relative path starts with a directory name, for example, output.
For details about how to parse the exported data file, see Overflow/Underflow Operator Data Collection and Analysis.
This function cannot be enabled when model or single-operator dump configuration is enabled. Otherwise, an error is returned.

The following gives a configuration example.

{
    "dump":{
        "dump_path":"output",
        "dump_debug":"on"
    }
}

Example Configuration (Operator Cache Information Aging)

Restrictions:

For an operator that is statically loaded, when acl.op.set_model_dir is called to load a single-operator model in the specified directory or acl.op.load is called to load a single-operator model, the aging configuration is invalid. That is, the operator information is not aged.
pyACL maintains two mapping queues, one for static-shape and the other for dynamic-shape operators. However, their maximum lengths are both determined by the max_opqueue_num parameter.
The value of max_opqueue_num is the sum of the number of single-operator models with statically loaded operators and the number of single-operator models with operators compiled online. Therefore, the value of max_opqueue_num must be greater than the number of single-operator models with statically loaded operators that are available in the current process; otherwise, the information about operators compiled online cannot be aged.

The following gives a configuration example.

{
        "max_opqueue_num": "10000"
}

Configuration File Example (Configuration of Error Information Reporting Mode)

Value range of the err_msg_mode parameter: 0 is the default value, indicating that error information is obtained by thread. 1 indicates that error information is obtained by process.

The following gives a configuration example:

{
        "err_msg_mode": "1"
}

Parent topic: System Configuration