ASCEND_GE_PY_PASS_PATH

Description

ASCEND_GE_PY_PASS_PATH is an environment variable for path discovery in the Graph Engine (GE) Python Pass system. It is used to instruct the GE engine to load the Python fusion Pass plugin written by the user from specific paths.

This environment variable controls a complete link from discovery to registration to execution.

1. When the pass loading process is started in the GE compilation phase, the C++ side checks whether ASCEND_GE_PY_PASS_PATH has been set and is not empty.
2. If it has been set, GE synchronizes this environment variable to the Python side through the C++/Python bridge.
3. The Python side scans and loads the pass module compiled by the user based on the path.
4. During module loading, users can use decorators such as @register_fusion_pass or @register_decompose_pass to register the pass with the Python registry.
5. The registration information then is sent back to PassRegistry on the C++ side and will be executed by the GE Pass scheduling framework in the subsequent compilation phase.

In the current phase, ASCEND_GE_PY_PASS_PATH is the main path discovered by the Python pass (not a fallback mechanism). The entry_points(group="ge.passes.plugins") automatic discovery mechanism will be added in later versions.

Configuration value:

ASCEND_GE_PY_PASS_PATH=<path1>[:<path2>[:...]]

Path requirements: Multiple paths are separated by colons (:). Each path can be a .py file or directory. Absolute paths are recommended.

Path type description:

Example

• Points to a single Python file.

  export ASCEND_GE_PY_PASS_PATH=/path/to/my_pass.py

• Points to a directory (all .py files and Python packages in the directory will be scanned).

  export ASCEND_GE_PY_PASS_PATH=/path/to/pass_dir/

• Multiple paths can be separated by colons (:).

  export ASCEND_GE_PY_PASS_PATH=/path/to/pass1.py:/path/to/pass_dir2/

Scanning Rules

• Directory scanning rules

  When the path points to a directory, the bootstrap module scans the directory based on the following rules:

  1. Files and subdirectories starting with an underscore (_) in the directory will be skipped and not scanned.
  2. .py files that do not start with an underscore (_) are directly loaded as independent modules.
  3. Subdirectories containing __init__.py are imported as Python packages using importlib.import_module().
  4. Subdirectories in the directory are scanned in sequence after being sorted by name.
• Module names

  Each module loaded through a file path is assigned a unique internal name in the format of _ge_py_pass_{stem}_{hash} to avoid conflicts with custom module names. The same file path will not be loaded repeatedly.

Restrictions

• This environment variable must be set before GE initialization. GE reads this variable when loading a pass for the first time during compilation. Runtime changes to the environment variable do not take effect.
• The .py file specified by the path must contain valid Python code, and at least one pass must be registered using the @register_fusion_pass or @register_decompose_pass decorator. Modules that do not register any pass will be loaded but will not take effect.
• The directory specified by the path must exist. Otherwise, FileNotFoundError will be thrown during pass loading.
• The file path must end with .py. Otherwise, ValueError will be thrown.
• If the environment variable is left empty or not set, GE will skip the Python pass loading process, which does not affect the normal loading of custom C++ passes.
• The same file path will be loaded only once. Repeated appearance in multiple path segments will not cause repeated registration.

Applicable Models

All processors