tessl/pypi-amdsmi

Python library for monitoring and managing AMD GPUs and CPUs with programmatic hardware metrics access

Overview

Eval results

Files

GPU Configuration and Control

Name: tessl/pypi-amdsmi
Author: tessl

Administrative functions for configuring and controlling AMD GPU settings including power management, clock frequencies, performance profiles, fan control, and system-level operations. These functions modify GPU behavior and typically require elevated privileges.

Important Notes

Most control functions require root/administrator privileges
These functions may not work correctly in virtualized environments (VMs, containers)
Improper use can cause system instability or hardware damage
Always verify settings are supported by your specific GPU model
Some changes may require a GPU reset or driver reload to take effect
Settings may be reset after system reboot or driver reload

Capabilities

Power Management

Control GPU power consumption limits and profiles.

def amdsmi_get_power_cap_info(processor_handle: processor_handle) -> Dict[str, Any]:
    """
    Get power cap information including current, default, and min/max limits.

    Retrieves comprehensive power cap settings and limits, including the current power cap,
    default cap, DPM (Dynamic Power Management) cap, and minimum/maximum allowed values.
    All values are in microwatts.

    Parameters:
    - processor_handle: Handle for the target GPU device

    Returns:
    - Dict[str, Any]: Dictionary containing:
      - "power_cap" (int): Current power cap in microwatts
      - "default_power_cap" (int): Default power cap in microwatts
      - "dpm_cap" (int): DPM power cap in microwatts
      - "min_power_cap" (int): Minimum allowed power cap in microwatts
      - "max_power_cap" (int): Maximum allowed power cap in microwatts

    Raises:
    - AmdSmiParameterException: If processor_handle is not valid
    - AmdSmiLibraryException: If unable to retrieve power cap information

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    power_cap = amdsmi.amdsmi_get_power_cap_info(device)
    print(f"Current Power Cap: {power_cap['power_cap'] / 1000000:.2f}W")
    print(f"Default Power Cap: {power_cap['default_power_cap'] / 1000000:.2f}W")
    print(f"Min Power Cap: {power_cap['min_power_cap'] / 1000000:.2f}W")
    print(f"Max Power Cap: {power_cap['max_power_cap'] / 1000000:.2f}W")
    print(f"DPM Cap: {power_cap['dpm_cap'] / 1000000:.2f}W")

    amdsmi.amdsmi_shut_down()
    ```
    """

def amdsmi_set_power_cap(
    processor_handle: processor_handle,
    sensor_ind: int,
    cap: int
) -> None:
    """
    Set the power cap limit for the GPU.

    Sets the maximum power consumption limit in microwatts. The GPU will throttle
    performance to stay within this limit.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - sensor_ind (int): Power sensor index (typically 0)
    - cap (int): Power cap in microwatts (e.g., 200000000 = 200W)

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Get current power cap info
    cap_info = amdsmi.amdsmi_get_power_cap_info(device)
    print(f"Default: {cap_info['default_power_cap'] / 1000000}W")
    print(f"Min: {cap_info['min_power_cap'] / 1000000}W")
    print(f"Max: {cap_info['max_power_cap'] / 1000000}W")

    # Set power cap to 150W
    amdsmi.amdsmi_set_power_cap(device, 0, 150000000)
    print("Power cap set to 150W")

    amdsmi.amdsmi_shut_down()
    ```

    Note:
    - Requires root privileges
    - Setting too low may cause instability
    - Verify cap_info limits before setting
    """

def amdsmi_get_gpu_power_profile_presets(
    processor_handle: processor_handle,
    sensor_idx: int
) -> Dict[str, Any]:
    """
    Get available power profile presets and current status.

    Retrieves information about available power profiles and which profile is currently
    active. Power profiles optimize GPU behavior for different workload types.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - sensor_idx (int): Sensor index (typically 0)

    Returns:
    - Dict[str, Any]: Dictionary containing:
      - "available_profiles" (int): Bitmask of available profiles
      - "current" (int): Currently active profile index
      - "num_profiles" (int): Number of available profiles

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On query failure

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    presets = amdsmi.amdsmi_get_gpu_power_profile_presets(device, 0)
    print(f"Available profiles mask: 0x{presets['available_profiles']:x}")
    print(f"Current profile: {presets['current']}")
    print(f"Number of profiles: {presets['num_profiles']}")

    amdsmi.amdsmi_shut_down()
    ```
    """

def amdsmi_set_gpu_power_profile(
    processor_handle: processor_handle,
    reserved: int,
    profile: AmdSmiPowerProfilePresetMasks
) -> None:
    """
    Set the GPU power profile preset.

    Configures the GPU to use a specific power/performance profile optimized
    for different workload types.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - reserved (int): Reserved parameter, set to 0
    - profile (AmdSmiPowerProfilePresetMasks): Power profile preset:
      - BOOTUP_DEFAULT: Default boot profile
      - 3D_FULL_SCREEN: Optimized for 3D applications
      - POWER_SAVING: Maximum power efficiency
      - VIDEO: Optimized for video playback/encoding
      - VR: Optimized for VR workloads
      - COMPUTE: Optimized for compute workloads
      - CUSTOM: Custom user-defined profile

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi
    from amdsmi import AmdSmiPowerProfilePresetMasks

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Query available profiles
    presets = amdsmi.amdsmi_get_gpu_power_profile_presets(device, 0)
    print("Available profiles:", presets)

    # Set compute-optimized profile
    amdsmi.amdsmi_set_gpu_power_profile(
        device,
        0,
        AmdSmiPowerProfilePresetMasks.COMPUTE
    )
    print("Power profile set to COMPUTE")

    amdsmi.amdsmi_shut_down()
    ```

    Note:
    - Requires root privileges
    - Profile availability varies by GPU model
    """

Clock Frequency Control

Manage GPU clock frequencies for different domains.

def amdsmi_get_clock_info(
    processor_handle: processor_handle,
    clock_type: AmdSmiClkType
) -> Dict[str, Any]:
    """
    Get comprehensive clock information for a specific clock domain.

    Retrieves detailed clock frequency information including current, minimum, maximum,
    and sleep frequencies for the specified clock domain. This provides complete visibility
    into clock behavior and limits.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - clock_type (AmdSmiClkType): Clock domain to query:
      - SYS: System clock
      - GFX: Graphics clock
      - MEM: Memory clock
      - SOC: SoC clock
      - DF: Data Fabric clock
      - DCEF: Display Controller Engine Fabric clock
      - PCIE: PCIe clock
      - And others (see AmdSmiClkType enum)

    Returns:
    - Dict[str, Any]: Dictionary containing:
      - "clk" (int): Current clock frequency in MHz
      - "min_clk" (int): Minimum clock frequency in MHz
      - "max_clk" (int): Maximum clock frequency in MHz
      - "sleep_clk" (int): Sleep/idle clock frequency in MHz (if available)

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On query failure

    Example:
    ```python
    import amdsmi
    from amdsmi import AmdSmiClkType

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Get GFX clock info
    gfx_clk = amdsmi.amdsmi_get_clock_info(device, AmdSmiClkType.GFX)
    print(f"GFX Clock: {gfx_clk['clk']} MHz")
    print(f"  Range: {gfx_clk['min_clk']} - {gfx_clk['max_clk']} MHz")
    print(f"  Sleep: {gfx_clk['sleep_clk']} MHz")

    # Get memory clock info
    mem_clk = amdsmi.amdsmi_get_clock_info(device, AmdSmiClkType.MEM)
    print(f"Memory Clock: {mem_clk['clk']} MHz")
    print(f"  Range: {mem_clk['min_clk']} - {mem_clk['max_clk']} MHz")

    amdsmi.amdsmi_shut_down()
    ```
    """

def amdsmi_set_gpu_clk_range(
    processor_handle: processor_handle,
    min_clk_value: int,
    max_clk_value: int,
    clk_type: AmdSmiClkType
) -> None:
    """
    Set the minimum and maximum clock frequency range.

    Constrains clock frequencies to operate within the specified range. Useful
    for limiting power consumption or ensuring minimum performance.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - min_clk_value (int): Minimum clock frequency in MHz
    - max_clk_value (int): Maximum clock frequency in MHz
    - clk_type (AmdSmiClkType): Clock domain to configure:
      - SYS: System clock
      - GFX: Graphics clock
      - MEM: Memory clock
      - SOC: SoC clock
      - DF: Data Fabric clock

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi
    from amdsmi import AmdSmiClkType

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Query current clock info
    clk_info = amdsmi.amdsmi_get_clock_info(device, AmdSmiClkType.GFX)
    print(f"Current GFX clock range: {clk_info['min_clk']}-{clk_info['max_clk']} MHz")

    # Limit GFX clock to 500-1500 MHz
    amdsmi.amdsmi_set_gpu_clk_range(device, 500, 1500, AmdSmiClkType.GFX)
    print("GFX clock range set to 500-1500 MHz")

    amdsmi.amdsmi_shut_down()
    ```

    Note:
    - Requires root privileges
    - Must use supported frequency values
    - Min must be less than max
    """

def amdsmi_set_gpu_clk_limit(
    processor_handle: processor_handle,
    clk_type: str,
    limit_type: str,
    value: int
) -> None:
    """
    Set a specific clock limit (min or max).

    Sets either the minimum or maximum clock frequency for a specific domain.
    Simpler alternative to set_gpu_clk_range for setting just one limit.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - clk_type (str): Clock type - "sclk" (system) or "mclk" (memory)
    - limit_type (str): Limit type - "min" or "max"
    - value (int): Clock frequency in MHz

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Set maximum system clock to 1800 MHz
    amdsmi.amdsmi_set_gpu_clk_limit(device, "sclk", "max", 1800)
    print("Max system clock set to 1800 MHz")

    # Set minimum memory clock to 500 MHz
    amdsmi.amdsmi_set_gpu_clk_limit(device, "mclk", "min", 500)
    print("Min memory clock set to 500 MHz")

    amdsmi.amdsmi_shut_down()
    ```

    Note:
    - Requires root privileges
    - String parameters are case-insensitive
    """

def amdsmi_set_clk_freq(
    processor_handle: processor_handle,
    clk_type: str,
    freq_bitmask: int
) -> None:
    """
    Set active clock frequency level using a bitmask.

    Selects which frequency levels should be active from the available
    discrete frequency levels. Multiple levels can be enabled simultaneously.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - clk_type (str): Clock type:
      - "sclk": System clock
      - "mclk": Memory clock
      - "fclk": Fabric clock
      - "socclk": SoC clock
    - freq_bitmask (int): Bitmask selecting frequency levels
      - Bit 0 = Level 0, Bit 1 = Level 1, etc.
      - Use 0xFF to enable all levels

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi
    from amdsmi import AmdSmiClkType

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Query available frequency levels
    freq_info = amdsmi.amdsmi_get_clk_freq(device, AmdSmiClkType.GFX)
    print(f"Available frequencies: {freq_info['frequency']}")

    # Enable only the highest frequency level (assume 7 levels, 0-6)
    # Bit 6 = 0b1000000 = 0x40
    amdsmi.amdsmi_set_clk_freq(device, "sclk", 0x40)
    print("Locked to highest frequency")

    # Enable all frequencies
    amdsmi.amdsmi_set_clk_freq(device, "sclk", 0xFF)
    print("All frequencies enabled")

    amdsmi.amdsmi_shut_down()
    ```

    Note:
    - Requires root privileges
    - May need to set performance level to MANUAL first
    """

Overdrive and Voltage Control

Advanced overclocking and voltage tuning.

def amdsmi_get_gpu_od_volt_info(processor_handle: processor_handle) -> Dict[str, Any]:
    """
    Get overdrive voltage/frequency curve information.

    Retrieves the current voltage and frequency curve settings for overdrive mode,
    including frequency ranges, voltage ranges, and voltage curve points.

    Parameters:
    - processor_handle: Handle for the target GPU device

    Returns:
    - Dict[str, Any]: Dictionary containing:
      - "sclk_freq_limits" (tuple): System clock frequency limits (min, max) in MHz
      - "mclk_freq_limits" (tuple): Memory clock frequency limits (min, max) in MHz
      - "curve.vc_points" (list): List of voltage curve points, each containing:
        - "frequency" (int): Frequency in MHz
        - "voltage" (int): Voltage in mV
      - Additional overdrive parameters specific to GPU

    Raises:
    - AmdSmiParameterException: If processor_handle is invalid
    - AmdSmiLibraryException: On query failure or if overdrive not supported

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    od_info = amdsmi.amdsmi_get_gpu_od_volt_info(device)
    print(f"SCLK Range: {od_info['sclk_freq_limits'][0]}-{od_info['sclk_freq_limits'][1]} MHz")
    print(f"MCLK Range: {od_info['mclk_freq_limits'][0]}-{od_info['mclk_freq_limits'][1]} MHz")

    print("\nVoltage Curve Points:")
    for i, point in enumerate(od_info.get('curve.vc_points', [])):
        print(f"  Point {i}: {point['frequency']} MHz @ {point['voltage']} mV")

    amdsmi.amdsmi_shut_down()
    ```
    """

def amdsmi_get_gpu_od_volt_curve_regions(
    processor_handle: processor_handle,
    num_regions: int
) -> List[Dict[str, Any]]:
    """
    Get overdrive voltage curve region information.

    Retrieves information about voltage curve regions, which define the valid
    frequency and voltage ranges for each point on the V/F curve.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - num_regions (int): Number of regions to query (typically 3)

    Returns:
    - List[Dict[str, Any]]: List of region dictionaries, each containing:
      - "freq_range" (tuple): Frequency range (min, max) in MHz
      - "volt_range" (tuple): Voltage range (min, max) in mV

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On query failure or if overdrive not supported

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    regions = amdsmi.amdsmi_get_gpu_od_volt_curve_regions(device, 3)
    for i, region in enumerate(regions):
        freq_min, freq_max = region['freq_range']
        volt_min, volt_max = region['volt_range']
        print(f"Region {i}:")
        print(f"  Frequency: {freq_min}-{freq_max} MHz")
        print(f"  Voltage: {volt_min}-{volt_max} mV")

    amdsmi.amdsmi_shut_down()
    ```
    """

def amdsmi_set_gpu_overdrive_level(
    processor_handle: processor_handle,
    overdrive_value: int
) -> None:
    """
    Set the GPU core overdrive percentage.

    Enables overclocking by allowing the GPU to run beyond its default
    specifications. Higher values increase performance but also power
    consumption and heat.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - overdrive_value (int): Overdrive percentage (0-20 typical, GPU-dependent)
      - 0: Disabled (default clocks)
      - 1-20: Percentage above default clocks

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Check current overdrive level
    current_od = amdsmi.amdsmi_get_gpu_overdrive_level(device)
    print(f"Current overdrive: {current_od}%")

    # Enable 5% overdrive
    amdsmi.amdsmi_set_gpu_overdrive_level(device, 5)
    print("Overdrive set to 5%")

    amdsmi.amdsmi_shut_down()
    ```

    Warning:
    - Overclocking can damage hardware if cooling is inadequate
    - May void warranty
    - Monitor temperatures carefully
    - Requires root privileges
    """

def amdsmi_set_gpu_od_clk_info(
    processor_handle: processor_handle,
    level: AmdSmiFreqInd,
    value: int,
    clk_type: AmdSmiClkType
) -> None:
    """
    Set overdrive clock frequency for a specific level.

    Configures custom clock frequencies for overdrive operation. Allows
    fine-grained control over frequency/voltage curve points.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - level (AmdSmiFreqInd): Frequency level index:
      - MIN: Minimum frequency level
      - MAX: Maximum frequency level
    - value (int): Clock frequency in MHz
    - clk_type (AmdSmiClkType): Clock domain (SYS, GFX, MEM, etc.)

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi
    from amdsmi import AmdSmiClkType, AmdSmiFreqInd

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Get current overdrive voltage info
    od_info = amdsmi.amdsmi_get_gpu_od_volt_info(device)
    print("SCLK limits:", od_info['sclk_freq_limits'])

    # Set maximum GFX clock to 1900 MHz
    amdsmi.amdsmi_set_gpu_od_clk_info(
        device,
        AmdSmiFreqInd.MAX,
        1900,
        AmdSmiClkType.GFX
    )
    print("Max GFX clock set to 1900 MHz")

    amdsmi.amdsmi_shut_down()
    ```

    Note:
    - Requires root privileges
    - Must be within hardware limits
    - Part of advanced overclocking workflow
    """

def amdsmi_set_gpu_od_volt_info(
    processor_handle: processor_handle,
    vpoint: int,
    clk_value: int,
    volt_value: int
) -> None:
    """
    Set overdrive voltage curve point.

    Configures voltage/frequency curve points for precise power/performance
    tuning. Allows undervolting or overvolting at specific frequencies.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - vpoint (int): Voltage curve point index (0-2 typically)
    - clk_value (int): Clock frequency for this point in MHz
    - volt_value (int): Voltage for this point in millivolts

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Get voltage curve info
    od_volt = amdsmi.amdsmi_get_gpu_od_volt_info(device)
    print("Voltage curve points:", od_volt['curve.vc_points'])

    # Set voltage curve point 2: 1800 MHz @ 1100 mV
    amdsmi.amdsmi_set_gpu_od_volt_info(device, 2, 1800, 1100)
    print("Voltage curve point 2: 1800 MHz @ 1100 mV")

    amdsmi.amdsmi_shut_down()
    ```

    Warning:
    - Incorrect voltage settings can damage hardware
    - Undervolting too much causes instability
    - Overvolting increases heat and wear
    - Requires root privileges
    - Advanced users only
    """

Performance Level Control

Manage GPU performance states and modes.

def amdsmi_get_gpu_perf_level(processor_handle: processor_handle) -> str:
    """
    Get the current GPU performance level.

    Retrieves the current performance level setting that controls how the GPU
    manages power and performance.

    Parameters:
    - processor_handle: Handle for the target GPU device

    Returns:
    - str: Performance level name:
      - "AUTO": Automatic management (default)
      - "LOW": Power saving mode
      - "HIGH": Maximum performance mode
      - "MANUAL": Manual control enabled
      - "STABLE_STD": Stable clocks for compute
      - "STABLE_PEAK": Peak stable clocks
      - "STABLE_MIN_MCLK": Minimum memory clock stable mode
      - "STABLE_MIN_SCLK": Minimum system clock stable mode
      - "DETERMINISM": Deterministic performance mode
      - "UNKNOWN": Unknown or unsupported level

    Raises:
    - AmdSmiParameterException: If processor_handle is invalid
    - AmdSmiLibraryException: On query failure

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    perf_level = amdsmi.amdsmi_get_gpu_perf_level(device)
    print(f"Current performance level: {perf_level}")

    amdsmi.amdsmi_shut_down()
    ```
    """

def amdsmi_set_gpu_perf_level(
    processor_handle: processor_handle,
    perf_level: AmdSmiDevPerfLevel
) -> None:
    """
    Set the GPU performance level.

    Configures how the GPU manages power and performance. Different levels
    control the aggressiveness of dynamic frequency and voltage scaling.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - perf_level (AmdSmiDevPerfLevel): Performance level:
      - AUTO: Automatic management (default)
      - LOW: Power saving mode
      - HIGH: Maximum performance mode
      - MANUAL: Manual control enabled
      - STABLE_STD: Stable clocks for compute
      - STABLE_PEAK: Peak stable clocks
      - STABLE_MIN_MCLK: Minimum memory clock stable mode
      - STABLE_MIN_SCLK: Minimum system clock stable mode
      - DETERMINISM: Deterministic performance mode

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi
    from amdsmi import AmdSmiDevPerfLevel

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Check current performance level
    current = amdsmi.amdsmi_get_gpu_perf_level(device)
    print(f"Current: {current}")

    # Set to high performance mode
    amdsmi.amdsmi_set_gpu_perf_level(device, AmdSmiDevPerfLevel.HIGH)
    print("Performance level: HIGH")

    # Set to manual mode for fine-grained clock control
    amdsmi.amdsmi_set_gpu_perf_level(device, AmdSmiDevPerfLevel.MANUAL)
    print("Performance level: MANUAL (enables manual clock control)")

    amdsmi.amdsmi_shut_down()
    ```

    Note:
    - Requires root privileges
    - MANUAL mode must be set before manual clock adjustments
    - STABLE modes useful for compute workloads
    """

def amdsmi_set_gpu_perf_determinism_mode(
    processor_handle: processor_handle,
    clk_value: int
) -> None:
    """
    Set GPU performance determinism mode.

    Enables deterministic performance by locking clocks to a specific frequency.
    Ensures consistent performance for benchmarking or compute workloads.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - clk_value (int): Clock frequency in MHz to lock to

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Lock GPU to 1600 MHz for deterministic performance
    amdsmi.amdsmi_set_gpu_perf_determinism_mode(device, 1600)
    print("Determinism mode enabled at 1600 MHz")

    amdsmi.amdsmi_shut_down()
    ```

    Note:
    - Requires root privileges
    - May need to set DETERMINISM performance level first
    - Useful for reproducible benchmark results
    """

Fan Control

Manage GPU cooling fan speed.

def amdsmi_get_gpu_fan_rpms(
    processor_handle: processor_handle,
    sensor_idx: int
) -> int:
    """
    Get GPU fan speed in RPM (revolutions per minute).

    Returns the current fan rotation speed in RPM for the specified fan sensor.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - sensor_idx (int): Fan sensor index (typically 0 for single-fan GPUs)

    Returns:
    - int: Fan speed in RPM

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On query failure

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    fan_rpm = amdsmi.amdsmi_get_gpu_fan_rpms(device, 0)
    print(f"Fan speed: {fan_rpm} RPM")

    amdsmi.amdsmi_shut_down()
    ```
    """

def amdsmi_get_gpu_fan_speed(
    processor_handle: processor_handle,
    sensor_idx: int
) -> int:
    """
    Get GPU fan speed as a percentage.

    Returns the current fan speed as a percentage of maximum speed.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - sensor_idx (int): Fan sensor index (typically 0 for single-fan GPUs)

    Returns:
    - int: Fan speed percentage (0-100)

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On query failure

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    fan_percent = amdsmi.amdsmi_get_gpu_fan_speed(device, 0)
    print(f"Fan speed: {fan_percent}%")

    amdsmi.amdsmi_shut_down()
    ```
    """

def amdsmi_get_gpu_fan_speed_max(
    processor_handle: processor_handle,
    sensor_idx: int
) -> int:
    """
    Get maximum GPU fan speed.

    Returns the maximum possible fan speed in RPM for the specified fan sensor.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - sensor_idx (int): Fan sensor index (typically 0 for single-fan GPUs)

    Returns:
    - int: Maximum fan speed in RPM

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On query failure

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    max_rpm = amdsmi.amdsmi_get_gpu_fan_speed_max(device, 0)
    current_rpm = amdsmi.amdsmi_get_gpu_fan_rpms(device, 0)
    percent = (current_rpm / max_rpm) * 100
    print(f"Fan: {current_rpm} / {max_rpm} RPM ({percent:.1f}%)")

    amdsmi.amdsmi_shut_down()
    ```
    """

def amdsmi_set_gpu_fan_speed(
    processor_handle: processor_handle,
    sensor_idx: int,
    fan_speed: int
) -> None:
    """
    Set GPU fan speed manually.

    Overrides automatic fan control and sets fan to a specific speed.
    Use for custom cooling profiles or quiet operation.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - sensor_idx (int): Fan sensor index (typically 0 for single-fan GPUs)
    - fan_speed (int): Fan speed as percentage (0-100) or value (0-255)

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Check current fan speed
    current_speed = amdsmi.amdsmi_get_gpu_fan_speed(device, 0)
    print(f"Current fan speed: {current_speed}%")

    # Set fan to 70%
    amdsmi.amdsmi_set_gpu_fan_speed(device, 0, 70)
    print("Fan speed set to 70%")

    # Set fan to maximum
    amdsmi.amdsmi_set_gpu_fan_speed(device, 0, 100)
    print("Fan speed set to 100%")

    amdsmi.amdsmi_shut_down()
    ```

    Warning:
    - Setting fan too low can cause overheating
    - Monitor temperatures when using manual fan control
    - Requires root privileges
    """

def amdsmi_reset_gpu_fan(
    processor_handle: processor_handle,
    sensor_idx: int
) -> None:
    """
    Reset GPU fan to automatic control.

    Restores automatic fan control, allowing the GPU to manage fan speed
    based on temperature and load.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - sensor_idx (int): Fan sensor index (typically 0 for single-fan GPUs)

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Manually control fan
    amdsmi.amdsmi_set_gpu_fan_speed(device, 0, 50)
    print("Fan set to 50%")

    # Later, restore automatic control
    amdsmi.amdsmi_reset_gpu_fan(device, 0)
    print("Fan control restored to automatic")

    amdsmi.amdsmi_shut_down()
    ```

    Note:
    - Requires root privileges
    - Recommended after manual fan control experiments
    """

PCIe Bandwidth Control

Manage PCIe link configuration.

def amdsmi_set_gpu_pci_bandwidth(
    processor_handle: processor_handle,
    bitmask: int
) -> None:
    """
    Set PCIe bandwidth/speed configuration.

    Controls PCIe link speed and width settings. Can be used to limit
    bandwidth for power savings or testing.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - bitmask (int): Bitmask specifying allowed PCIe configurations
      - Encoding varies by hardware
      - Bits represent different speed/width combinations

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Query current PCIe configuration
    pcie_info = amdsmi.amdsmi_get_gpu_pci_bandwidth(device)
    print("Transfer rates:", pcie_info['transfer_rate'])

    # Set PCIe bandwidth (bitmask depends on hardware)
    # Consult hardware documentation for valid values
    amdsmi.amdsmi_set_gpu_pci_bandwidth(device, 0x1)
    print("PCIe bandwidth configured")

    amdsmi.amdsmi_shut_down()
    ```

    Note:
    - Requires root privileges
    - Bitmask values are hardware-specific
    - May affect system stability
    - Consult documentation for GPU model
    """

System-Level Operations

GPU reset and driver management.

def amdsmi_reset_gpu(processor_handle: processor_handle) -> None:
    """
    Reset the GPU.

    Performs a hardware reset of the GPU. This will terminate all running
    applications using the GPU and reset all settings.

    Parameters:
    - processor_handle: Handle for the target GPU device

    Raises:
    - AmdSmiParameterException: If processor_handle is invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Reset GPU (use with caution!)
    print("Resetting GPU...")
    amdsmi.amdsmi_reset_gpu(device)
    print("GPU reset complete")

    amdsmi.amdsmi_shut_down()
    ```

    Warning:
    - Terminates all GPU workloads immediately
    - May crash applications using the GPU
    - Resets all GPU settings to defaults
    - Use only when necessary (hung GPU, etc.)
    - Requires root privileges
    """

def amdsmi_gpu_driver_reload() -> None:
    """
    Reload the GPU driver.

    Unloads and reloads the AMD GPU driver. This affects all GPUs in the
    system and will terminate all GPU applications.

    Raises:
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()

    # Reload driver (affects all GPUs!)
    print("Reloading GPU driver...")
    amdsmi.amdsmi_gpu_driver_reload()
    print("Driver reload complete")

    # Re-initialize after driver reload
    amdsmi.amdsmi_shut_down()
    amdsmi.amdsmi_init()

    # Verify GPUs are available
    devices = amdsmi.amdsmi_get_processor_handles()
    print(f"Found {len(devices)} GPUs after reload")

    amdsmi.amdsmi_shut_down()
    ```

    Warning:
    - Affects ALL GPUs in the system
    - Terminates ALL GPU applications
    - May cause system instability
    - Use only when absolutely necessary
    - Requires root privileges
    - May require re-initialization of amdsmi
    """

Advanced Features

SoC, XGMI, and isolation control.

def amdsmi_set_soc_pstate(
    processor_handle: processor_handle,
    policy_id: int
) -> None:
    """
    Set SoC performance state policy.

    Configures the System-on-Chip performance state management policy.
    Affects power/performance trade-offs for the SoC components.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - policy_id (int): Performance state policy identifier
      - 0: Default policy
      - Other values: Hardware-specific policies

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Query current SoC P-state
    current = amdsmi.amdsmi_get_soc_pstate(device)
    print(f"Current SoC P-state: {current}")

    # Set SoC P-state policy
    amdsmi.amdsmi_set_soc_pstate(device, 0)
    print("SoC P-state policy set")

    amdsmi.amdsmi_shut_down()
    ```

    Note:
    - Requires root privileges
    - Policy IDs are hardware-specific
    - For APUs and SoC-based GPUs
    """

def amdsmi_set_xgmi_plpd(
    processor_handle: processor_handle,
    policy_id: int
) -> None:
    """
    Set XGMI per-link power down policy.

    Configures power management for XGMI links (high-speed GPU-to-GPU
    interconnects). Controls when inactive links are powered down.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - policy_id (int): Power down policy identifier
      - 0: Default policy
      - Other values: Hardware-specific policies

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Query current XGMI PLPD setting
    current = amdsmi.amdsmi_get_xgmi_plpd(device)
    print(f"Current XGMI PLPD: {current}")

    # Set XGMI per-link power down policy
    amdsmi.amdsmi_set_xgmi_plpd(device, 0)
    print("XGMI PLPD policy set")

    amdsmi.amdsmi_shut_down()
    ```

    Note:
    - Requires root privileges
    - Only relevant for multi-GPU systems with XGMI
    - Policy IDs are hardware-specific
    """

def amdsmi_set_gpu_process_isolation(
    processor_handle: processor_handle,
    pisolate: int
) -> None:
    """
    Set GPU process isolation mode.

    Configures process isolation settings for the GPU, controlling how
    processes share GPU resources.

    Parameters:
    - processor_handle: Handle for the target GPU device
    - pisolate (int): Isolation setting
      - 0: Isolation disabled
      - 1: Isolation enabled
      - Other values may be hardware-specific

    Raises:
    - AmdSmiParameterException: If parameters are invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Query current isolation setting
    current = amdsmi.amdsmi_get_gpu_process_isolation(device)
    print(f"Current isolation: {current}")

    # Enable process isolation
    amdsmi.amdsmi_set_gpu_process_isolation(device, 1)
    print("Process isolation enabled")

    amdsmi.amdsmi_shut_down()
    ```

    Note:
    - Requires root privileges
    - May affect multi-process GPU usage
    - Feature availability varies by GPU
    """

def amdsmi_clean_gpu_local_data(processor_handle: processor_handle) -> None:
    """
    Clean GPU local data.

    Clears GPU-local data structures and caches. May be used for cleanup
    or troubleshooting purposes.

    Parameters:
    - processor_handle: Handle for the target GPU device

    Raises:
    - AmdSmiParameterException: If processor_handle is invalid
    - AmdSmiLibraryException: On operation failure or insufficient privileges

    Example:
    ```python
    import amdsmi

    amdsmi.amdsmi_init()
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Clean GPU local data
    amdsmi.amdsmi_clean_gpu_local_data(device)
    print("GPU local data cleaned")

    amdsmi.amdsmi_shut_down()
    ```

    Note:
    - Requires root privileges
    - Use case and behavior is hardware-specific
    - Typically used for troubleshooting
    """

Usage Examples

Complete Power Management

Configure power cap and profile:

import amdsmi
from amdsmi import AmdSmiPowerProfilePresetMasks

amdsmi.amdsmi_init()

try:
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Get power cap information
    cap_info = amdsmi.amdsmi_get_power_cap_info(device)
    print(f"Power Cap Range: {cap_info['min_power_cap']/1e6:.0f}W - "
          f"{cap_info['max_power_cap']/1e6:.0f}W")
    print(f"Default: {cap_info['default_power_cap']/1e6:.0f}W")

    # Set conservative power cap (80% of max)
    target_cap = int(cap_info['max_power_cap'] * 0.8)
    amdsmi.amdsmi_set_power_cap(device, 0, target_cap)
    print(f"Power cap set to {target_cap/1e6:.0f}W")

    # Set compute-optimized profile
    amdsmi.amdsmi_set_gpu_power_profile(
        device,
        0,
        AmdSmiPowerProfilePresetMasks.COMPUTE
    )
    print("Power profile: COMPUTE")

    # Verify settings
    power_info = amdsmi.amdsmi_get_power_info(device)
    print(f"Current power: {power_info['current_socket_power']/1000:.2f}W")

finally:
    amdsmi.amdsmi_shut_down()

Clock Frequency Tuning

Lock GPU to specific frequencies:

import amdsmi
from amdsmi import AmdSmiDevPerfLevel, AmdSmiClkType

amdsmi.amdsmi_init()

try:
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Get available frequency levels
    gfx_freqs = amdsmi.amdsmi_get_clk_freq(device, AmdSmiClkType.GFX)
    mem_freqs = amdsmi.amdsmi_get_clk_freq(device, AmdSmiClkType.MEM)

    print("Available GFX frequencies:", gfx_freqs['frequency'])
    print("Available MEM frequencies:", mem_freqs['frequency'])

    # Enable manual mode
    amdsmi.amdsmi_set_gpu_perf_level(device, AmdSmiDevPerfLevel.MANUAL)
    print("Performance level set to MANUAL")

    # Lock to specific frequency range
    # GFX: 800-1500 MHz
    amdsmi.amdsmi_set_gpu_clk_range(device, 800, 1500, AmdSmiClkType.GFX)
    print("GFX clock range: 800-1500 MHz")

    # Memory: 500-800 MHz
    amdsmi.amdsmi_set_gpu_clk_range(device, 500, 800, AmdSmiClkType.MEM)
    print("MEM clock range: 500-800 MHz")

    # Verify new ranges
    gfx_info = amdsmi.amdsmi_get_clock_info(device, AmdSmiClkType.GFX)
    mem_info = amdsmi.amdsmi_get_clock_info(device, AmdSmiClkType.MEM)

    print(f"GFX: {gfx_info['clk']} MHz ({gfx_info['min_clk']}-{gfx_info['max_clk']})")
    print(f"MEM: {mem_info['clk']} MHz ({mem_info['min_clk']}-{mem_info['max_clk']})")

    # Return to automatic mode
    amdsmi.amdsmi_set_gpu_perf_level(device, AmdSmiDevPerfLevel.AUTO)
    print("Returned to AUTO performance level")

finally:
    amdsmi.amdsmi_shut_down()

Custom Fan Curve

Implement temperature-based fan control:

import amdsmi
from amdsmi import AmdSmiTemperatureType, AmdSmiTemperatureMetric
import time

def set_fan_speed_for_temp(device, sensor_idx=0):
    """Set fan speed based on temperature."""

    # Get current temperature
    temp = amdsmi.amdsmi_get_temp_metric(
        device,
        AmdSmiTemperatureType.EDGE,
        AmdSmiTemperatureMetric.CURRENT
    )
    temp_c = temp / 1000  # Convert from millidegrees

    # Custom fan curve
    if temp_c < 40:
        fan_speed = 30
    elif temp_c < 50:
        fan_speed = 40
    elif temp_c < 60:
        fan_speed = 50
    elif temp_c < 70:
        fan_speed = 65
    elif temp_c < 80:
        fan_speed = 80
    else:
        fan_speed = 100

    # Apply fan speed
    amdsmi.amdsmi_set_gpu_fan_speed(device, sensor_idx, fan_speed)

    return temp_c, fan_speed

amdsmi.amdsmi_init()

try:
    device = amdsmi.amdsmi_get_processor_handles()[0]

    print("Custom fan control active (Ctrl+C to stop)")
    print("Temperature-based fan curve:")
    print("  <40C: 30%  |  40-50C: 40%  |  50-60C: 50%")
    print("  60-70C: 65%  |  70-80C: 80%  |  >80C: 100%")
    print()

    try:
        while True:
            temp, fan = set_fan_speed_for_temp(device, 0)
            print(f"Temp: {temp:.1f}C  Fan: {fan}%", end='\r')
            time.sleep(2)
    except KeyboardInterrupt:
        print("\n\nRestoring automatic fan control...")
        amdsmi.amdsmi_reset_gpu_fan(device, 0)
        print("Automatic fan control restored")

finally:
    amdsmi.amdsmi_shut_down()

Safe Overclocking Workflow

Incrementally test overclocking:

import amdsmi
from amdsmi import AmdSmiDevPerfLevel, AmdSmiClkType, AmdSmiFreqInd
import time

def safe_overclock_test(device, target_mhz, duration_sec=60):
    """Test GPU stability at target frequency."""

    print(f"\nTesting {target_mhz} MHz for {duration_sec} seconds...")

    # Get baseline
    start_metrics = amdsmi.amdsmi_get_gpu_metrics_info(device)
    start_temp = start_metrics.get('temperature_edge', 0)

    # Set target frequency
    amdsmi.amdsmi_set_gpu_clk_limit(device, "sclk", "max", target_mhz)

    # Monitor for duration
    max_temp = 0
    for i in range(duration_sec):
        metrics = amdsmi.amdsmi_get_gpu_metrics_info(device)
        temp = metrics.get('temperature_edge', 0)
        clock = metrics.get('current_gfxclk', 0)

        max_temp = max(max_temp, temp)

        print(f"  [{i+1}/{duration_sec}s] Clock: {clock} MHz  "
              f"Temp: {temp}C  Max: {max_temp}C", end='\r')

        # Safety check
        if temp > 85:
            print("\n  WARNING: Temperature too high!")
            return False

        time.sleep(1)

    print(f"\n  Test passed! Max temp: {max_temp}C")
    return True

amdsmi.amdsmi_init()

try:
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Get current configuration
    clk_info = amdsmi.amdsmi_get_clock_info(device, AmdSmiClkType.GFX)
    base_clock = clk_info['max_clk']

    print(f"Base max clock: {base_clock} MHz")
    print("\n=== Starting safe overclock test ===")

    # Enable manual mode
    amdsmi.amdsmi_set_gpu_perf_level(device, AmdSmiDevPerfLevel.MANUAL)

    # Test incrementally higher clocks
    test_clocks = [
        base_clock + 50,
        base_clock + 100,
        base_clock + 150,
    ]

    stable_clock = base_clock

    for test_clock in test_clocks:
        if safe_overclock_test(device, test_clock, 30):
            stable_clock = test_clock
        else:
            print(f"\nStopping at {stable_clock} MHz")
            break

    print(f"\n=== Results ===")
    print(f"Stable overclock: {stable_clock} MHz")
    print(f"Gain: +{stable_clock - base_clock} MHz "
          f"({((stable_clock/base_clock)-1)*100:.1f}%)")

    # Reset to auto mode
    amdsmi.amdsmi_set_gpu_perf_level(device, AmdSmiDevPerfLevel.AUTO)
    print("\nReturned to AUTO mode")

finally:
    amdsmi.amdsmi_shut_down()

Undervolting for Efficiency

Reduce power consumption via undervolting:

import amdsmi
from amdsmi import AmdSmiDevPerfLevel

amdsmi.amdsmi_init()

try:
    device = amdsmi.amdsmi_get_processor_handles()[0]

    # Get current voltage/frequency info
    od_info = amdsmi.amdsmi_get_gpu_od_volt_info(device)
    print("Current voltage curve:")
    for point in od_info.get('curve.vc_points', []):
        print(f"  {point}")

    # Enable manual mode
    amdsmi.amdsmi_set_gpu_perf_level(device, AmdSmiDevPerfLevel.MANUAL)

    # Example: Undervolt by reducing voltage at each point
    # These are example values - adjust for your GPU!
    undervolt_points = [
        (0, 800, 850),   # Point 0: 800 MHz @ 850 mV
        (1, 1200, 950),  # Point 1: 1200 MHz @ 950 mV
        (2, 1600, 1050), # Point 2: 1600 MHz @ 1050 mV
    ]

    print("\nApplying undervolt...")
    for vpoint, freq, voltage in undervolt_points:
        amdsmi.amdsmi_set_gpu_od_volt_info(device, vpoint, freq, voltage)
        print(f"  Point {vpoint}: {freq} MHz @ {voltage} mV")

    # Monitor power savings
    print("\nMonitoring for 30 seconds...")
    power_samples = []

    for i in range(30):
        power_info = amdsmi.amdsmi_get_power_info(device)
        current_power = power_info.get('current_socket_power', 0)
        if current_power != "N/A":
            power_samples.append(current_power / 1000)
            avg_power = sum(power_samples) / len(power_samples)
            print(f"  Power: {current_power/1000:.1f}W  "
                  f"Avg: {avg_power:.1f}W", end='\r')
        time.sleep(1)

    print(f"\n\nAverage power: {avg_power:.1f}W")

    # Return to defaults
    amdsmi.amdsmi_set_gpu_perf_level(device, AmdSmiDevPerfLevel.AUTO)
    print("Returned to AUTO mode (voltage reset)")

except Exception as e:
    print(f"Error: {e}")
    print("Note: Voltage control requires specific GPU support")

finally:
    amdsmi.amdsmi_shut_down()

Related Types

AmdSmiDevPerfLevel

Performance level enumeration:

AUTO - Automatic performance management (default)
LOW - Low performance/power mode
HIGH - High performance mode
MANUAL - Manual control enabled
STABLE_STD - Stable clocks for compute workloads
STABLE_PEAK - Peak stable clocks
STABLE_MIN_MCLK - Minimum memory clock stable mode
STABLE_MIN_SCLK - Minimum system clock stable mode
DETERMINISM - Deterministic performance mode

AmdSmiPowerProfilePresetMasks

Power profile presets:

BOOTUP_DEFAULT - Default boot profile
3D_FULL_SCREEN - Optimized for 3D applications
POWER_SAVING - Maximum power efficiency
VIDEO - Optimized for video playback/encoding
VR - Optimized for VR workloads
COMPUTE - Optimized for compute workloads
CUSTOM - Custom user-defined profile

AmdSmiClkType

Clock domain types (see GPU Monitoring documentation for complete list).

AmdSmiFreqInd

Frequency index for overdrive:

MIN - Minimum frequency level
MAX - Maximum frequency level
INVALID - Invalid index

Best Practices

Safety Guidelines

Always verify current settings before making changes

cap_info = amdsmi.amdsmi_get_power_cap_info(device)
# Check min/max before setting

Monitor temperatures when overclocking

temp = amdsmi.amdsmi_get_temp_metric(device, ...)
if temp / 1000 > 85:  # 85°C threshold
    # Reduce clocks or abort

Use try/finally for cleanup

try:
    amdsmi.amdsmi_set_gpu_perf_level(device, MANUAL)
    # ... make changes ...
finally:
    amdsmi.amdsmi_set_gpu_perf_level(device, AUTO)

Test incrementally
- Don't jump to maximum overclock
- Test each step for stability
- Increase by small increments (50 MHz)

Keep defaults documented

# Save original settings
original_perf = amdsmi.amdsmi_get_gpu_perf_level(device)
# ... make changes ...
# Restore when done
amdsmi.amdsmi_set_gpu_perf_level(device, original_perf)

Performance Tuning Workflow

Baseline measurement
- Record current performance and power
- Note default clock frequencies
- Document temperature behavior

Enable manual control

amdsmi.amdsmi_set_gpu_perf_level(device, AmdSmiDevPerfLevel.MANUAL)

Make incremental changes
- Adjust one parameter at a time
- Test stability after each change
- Monitor temperatures continuously
Validate stability
- Run workloads for extended periods
- Check for artifacts or errors
- Verify consistent performance

Return to automatic mode when done

amdsmi.amdsmi_set_gpu_perf_level(device, AmdSmiDevPerfLevel.AUTO)

Common Use Cases

Gaming/Graphics Performance

Set performance level to HIGH
Enable 3D_FULL_SCREEN power profile
Monitor temperatures

Compute Workloads

Use STABLE_STD or STABLE_PEAK performance level
Set COMPUTE power profile
Lock clocks for consistency

Power Efficiency

Reduce power cap
Use POWER_SAVING profile
Limit maximum clock frequencies

Silent Operation

Set custom fan curve (low speeds)
Reduce power cap
Limit maximum clocks

Notes

All control functions require root/administrator privileges on most systems
Settings are typically volatile and reset on reboot or driver reload
Not all functions work in virtualized environments (VMs, Docker containers)
GPU support varies - some functions may not be available on all hardware
Always consult your GPU's specifications before overclocking or voltage adjustments
Improper settings can cause system crashes, data loss, or hardware damage
Fan control requires manual monitoring to prevent overheating
Performance levels must be set to MANUAL before manual clock control
XGMI and SoC functions are only relevant for specific GPU configurations
Some settings may require a GPU reset to take effect
Driver reload affects all GPUs in the system simultaneously
Process isolation features vary significantly by GPU generation

tessl/pypi-amdsmi

gpu-control.mddocs/reference/

GPU Configuration and Control

Important Notes

Capabilities

Power Management

Clock Frequency Control

Overdrive and Voltage Control

Performance Level Control

Fan Control

PCIe Bandwidth Control

System-Level Operations

Advanced Features

Usage Examples

Complete Power Management

Clock Frequency Tuning

Custom Fan Curve

Safe Overclocking Workflow

Undervolting for Efficiency

Related Types

AmdSmiDevPerfLevel

AmdSmiPowerProfilePresetMasks

AmdSmiClkType

AmdSmiFreqInd

Best Practices

Safety Guidelines

Performance Tuning Workflow

Common Use Cases

Notes

See Also

tessl/pypi-amdsmi

gpu-control.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/reference/

GPU Configuration and Control

Important Notes

Capabilities

Power Management

Clock Frequency Control

Overdrive and Voltage Control

Performance Level Control

Fan Control

PCIe Bandwidth Control

System-Level Operations

Advanced Features

Usage Examples

Complete Power Management

Clock Frequency Tuning

Custom Fan Curve

Safe Overclocking Workflow

Undervolting for Efficiency

Related Types

AmdSmiDevPerfLevel

AmdSmiPowerProfilePresetMasks

AmdSmiClkType

AmdSmiFreqInd

Best Practices

Safety Guidelines

Performance Tuning Workflow

Common Use Cases

Notes

See Also

gpu-control.mddocs/reference/