rocm-systems/projects/amdsmi/docs/how-to/amdsmi-py-lib.md

myst

myst
html_meta description lang=en keywords Get started with the AMD SMI Python interface. api, smi, lib, py, system, management, interface, ROCm

AMD SMI Python interface overview

The AMD SMI Python interface provides a convenient way to interact with AMD hardware through a simple and accessible API.

Refer to the [Python library API reference](../reference/amdsmi-py-api.md).

Prerequisites

Before get started, make sure your environment satisfies the following prerequisites. See the requirements section for more information.

1. Ensure amdgpu drivers are installed properly for initialization.

2. Export LD_LIBRARY_PATH to the amdsmi installation directory.

   export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/rocm/lib:/opt/rocm/lib64:
   

3. Install Python 3.6.8+.

Get started

``hipcc`` and other compilers will not automatically link in the ``libamd_smi``
dynamic library. To compile code that uses the AMD SMI library API, ensure the
``libamd_smi.so`` can be located by setting the ``LD_LIBRARY_PATH`` environment
variable to the directory containing ``librocm_smi64.so`` (usually
``/opt/rocm/lib``) or by passing the ``-lamd_smi`` flag to the compiler.

The environment variable ``AMDSMI_GPU_METRICS_CACHE_MS`` may be set to
control the internal GPU metrics cache duration (ms).
Default 1, set to 0 to disable.

The environment variable ``AMDSMI_ASIC_INFO_CACHE_MS`` may be set to
control the internal GPU asic info cache duration (ms).
Default 10000 ms, set to 0 to disable.

You can apply them in one of two ways:

1. In Python code (before the AMDSMI library loads):

import os
os.environ["AMDSMI_GPU_METRICS_CACHE_MS"] = "200"
from amdsmi import *

2. On the shell when invoking Python:

AMDSMI_GPU_METRICS_CACHE_MS=200 python tools/amdsmi_quick_start.py

To get started, the amdsmi folder should be copied and placed next to the importing script. Import it as follows:

from amdsmi import *

try:
    amdsmi_init()

    # amdsmi calls ...

except AmdSmiException as e:
    print(e)
finally:
    try:
        amdsmi_shut_down()
    except AmdSmiException as e:
        print(e)

(py_lib_fs)=

Folder structure

File name	Description
__init__.py	Python package initialization file
amdsmi_interface.py	Amdsmi library Python interface
amdsmi_wrapper.py	Python wrapper around amdsmi binary
amdsmi_exception.py	Amdsmi exceptions Python file

(py_usage)=

Usage

An application using AMD SMI must call amdsmi_init() to initialize the AMI SMI library before all other calls. This call initializes the internal data structures required for subsequent AMD SMI operations. In the call, a flag can be passed to indicate if the application is interested in a specific device type.

amdsmi_shut_down() must be the last call to properly close connection to driver and make sure that any resources held by AMD SMI are released.

Refer to the [Python library API reference](../reference/amdsmi-py-api.md).

(py_exceptions)=

Exceptions

All exceptions are in amdsmi_exception.py file.

Exceptions that can be thrown by AMD SMI are:

• AmdSmiException: base amdsmi exception class

• AmdSmiLibraryException: derives base AmdSmiException class and represents errors that can occur in amdsmi-lib. When this exception is thrown, err_code and err_info are set. err_code is an integer that corresponds to errors that can occur in amdsmi-lib and err_info is a string that explains the error that occurred.

  try:
      num_of_GPUs = len(amdsmi_get_processor_handles())
  except amdsmi_exception.AmdSmiLibraryException as e:
      print("Unable to get processor handles, error: {} {}".format(str(e.get_error_code()), e.err_info))
  

• AmdSmiParameterException: Derives base AmdSmiException class and represents errors related to invaild parameters passed to functions. When this exception is thrown, err_msg is set and it explains what is the actual and expected type of the parameters.

  For example:

  try:
      processor_handles = amdsmi_get_cpusocket_handles()
      if len(processor_handles) == 0:
          print("No CPU sockets on machine")
      else:
          for processor in processor_handles:
              temperature = amdsmi_get_cpu_socket_temperature(processor)
              print(temperature)
  except amdsmi_exception.AmdSmiParameterException as e:
      print("Invalid parameter error: {} {}".format(str(e.get_error_code()), e.err_msg))
  except amdsmi_exception.AmdSmiLibraryException as e:
      print("Unable to get processor handles, error: {} {}".format(str(e.get_error_code()), e.err_info))