For the complete documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /get-started.md).

Python class

ClockStats

ClockStats

class max.profiler.gpu.ClockStats(core_mhz, core_max_mhz, mem_mhz, mem_max_mhz, throttle_reasons)

source

Bases: Struct

Current and maximum GPU clock rates plus throttle reasons.

Captures the core (SM/graphics on NVIDIA, system clock on AMD) and memory clock rates measured at sample time along with the device’s boost ceiling for each domain. Consumers can compare current to max clocks (or inspect throttle_reasons) to detect runs whose performance is limited by hardware throttling rather than the workload itself.

throttle_reasons is a list of vendor-neutral ThrottleReason values. Note that "gpu_idle" is reported whenever the GPU is idle, so a non-empty list does not on its own indicate throttling – intersect with HARDWARE_THROTTLE_REASONS to detect hardware-induced throttling specifically. On AMD, throttle_reasons is None because ROCm-SMI does not expose an equivalent single-call API.

Parameters:

• core_mhz (int)
• core_max_mhz (int)
• mem_mhz (int | None)
• mem_max_mhz (int | None)
• throttle_reasons (list[Literal['gpu_idle', 'applications_clocks_setting', 'sw_power_cap', 'hw_slowdown', 'sync_boost', 'sw_thermal_slowdown', 'hw_thermal_slowdown', 'hw_power_brake_slowdown', 'display_clock_setting']] | None)

core_max_mhz

core_max_mhz: int

source

Maximum (boost) core clock rate in MHz.

core_mhz

core_mhz: int

source

Current core clock rate in MHz (SM clock on NVIDIA, system clock on AMD).

mem_max_mhz

mem_max_mhz: int | None

source

Maximum (boost) memory clock rate in MHz, or None if the vendor library did not report it.

mem_mhz

mem_mhz: int | None

source

Current memory clock rate in MHz, or None if the vendor library did not report it.

throttle_reasons

throttle_reasons: list[Literal['gpu_idle', 'applications_clocks_setting', 'sw_power_cap', 'hw_slowdown', 'sync_boost', 'sw_thermal_slowdown', 'hw_thermal_slowdown', 'hw_power_brake_slowdown', 'display_clock_setting']] | None

source

Vendor-neutral reasons the clock is below boost.

"gpu_idle" is reported whenever the GPU is idle, so consumers should intersect with HARDWARE_THROTTLE_REASONS when checking for hardware throttling. None when the vendor library does not expose a throttle-reason API.