gpu
zeus.device.gpu
Abstraction layer for GPU devices.
The main function of this module is get_gpus
,
which returns a GPU Manager object specific to the platform.
Important
In theory, any NVIDIA GPU would be supported. On the other hand, for AMD GPUs, we currently only support ROCm 6.1 and later.
Getting handles to GPUs
The main API exported from this module is the get_gpus
function. It returns either
NVIDIAGPUs
or AMDGPUs
depending on the platform.
from zeus.device import get_gpus
gpus = get_gpus()
Calling GPU management APIs
GPU management library APIs are mapped to methods on GPU
.
For example, for NVIDIA GPUs (which uses pynvml
), you would have called:
handle = pynvml.nvmlDeviceGetHandleByIndex(gpu_index)
constraints = pynvml.nvmlDeviceGetPowerManagementLimitConstraints(handle)
With the Zeus GPU abstraction layer, you would now call:
gpus = get_gpus() # returns an NVIDIAGPUs object
constraints = gpus.getPowerManagementLimitConstraints(gpu_index)
Non-blocking calls
Some implementations of GPU
support non-blocking calls to setters.
If non-blocking calls are not supported, setting block
will be ignored and the call will block.
Check GPU.supports_non_blocking
to see if non-blocking calls are supported.
Note that non-blocking calls will not raise exceptions even if the call fails.
Currently, only ZeusdNVIDIAGPU
supports non-blocking calls
to methods that set the GPU's power limit, GPU frequency, memory frequency, and persistence mode.
This is possible because the Zeus daemon supports a block: bool
parameter in HTTP requests,
which can be set to False
to make the call return immediately without checking the result.
Error handling
The following exceptions are defined in this module:
ZeusGPUInitError
: Base class for initialization errors.ZeusGPUInvalidArgError
: Error for invalid arguments.ZeusGPUNotSupportedError
: Error for unsupported GPUs.ZeusGPUNoPermissionError
: Error for permission issues.ZeusGPUAlreadyInitializedError
: Error for reinitialization.ZeusGPUNotFoundError
: Error for missing GPUs.ZeusGPUInsufficientSizeError
: Error for insufficient buffer size.ZeusGPUInsufficientPowerError
: Error for insufficient power.ZeusGPUDriverNotLoadedError
: Error for driver issues.ZeusGPUTimeoutError
: Error for timeout issues.ZeusGPUIRQError
: Error for IRQ issues.ZeusGPULibraryNotFoundError
: Error for missing libraries.ZeusGPUFunctionNotFoundError
: Error for missing functions.ZeusGPUCorruptedInfoROMError
: Error for corrupted info ROM.ZeusGPULostError
: Error for lost GPUs.ZeusGPUResetRequiredError
: Error for GPUs requiring reset.ZeusGPUOperatingSystemError
: Error for OS issues.ZeusGPULibRMVersionMismatchError
: Error for library version mismatch.ZeusGPUMemoryError
: Error for memory issues.ZeusGPUUnknownError
: Error for unknown issues.
ZeusBaseGPUError
Bases: ZeusBaseError
Zeus base GPU exception class.
Source code in zeus/device/exception.py
6 7 8 9 10 11 |
|
__init__
__init__(message)
Source code in zeus/device/exception.py
9 10 11 |
|
GPU
Bases: ABC
Abstract base class for managing one GPU.
For each method, child classes should call into vendor-specific GPU management libraries (e.g., NVML for NVIDIA GPUs).
Source code in zeus/device/gpu/common.py
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 |
|
supports_nonblocking_setters
abstractmethod
property
supports_nonblocking_setters
Return True if the GPU object supports non-blocking configuration setters.
__init__
__init__(gpu_index)
Source code in zeus/device/gpu/common.py
23 24 25 |
|
getName
abstractmethod
getName()
Return the name of the GPU model.
Source code in zeus/device/gpu/common.py
33 34 35 36 |
|
getPowerManagementLimitConstraints
abstractmethod
getPowerManagementLimitConstraints()
Return the minimum and maximum power management limits. Units: mW.
Source code in zeus/device/gpu/common.py
38 39 40 41 |
|
setPowerManagementLimit
abstractmethod
setPowerManagementLimit(power_limit_mw, _block=True)
Set the GPU's power management limit. Unit: mW.
Source code in zeus/device/gpu/common.py
43 44 45 46 |
|
resetPowerManagementLimit
abstractmethod
resetPowerManagementLimit(_block=True)
Reset the GPU's power management limit to the default value.
Source code in zeus/device/gpu/common.py
48 49 50 51 |
|
setPersistenceMode
abstractmethod
setPersistenceMode(enabled, _block=True)
Set persistence mode.
Source code in zeus/device/gpu/common.py
53 54 55 56 |
|
getSupportedMemoryClocks
abstractmethod
getSupportedMemoryClocks()
Return a list of supported memory clock frequencies. Units: MHz.
Source code in zeus/device/gpu/common.py
58 59 60 61 |
|
setMemoryLockedClocks
abstractmethod
setMemoryLockedClocks(
min_clock_mhz, max_clock_mhz, _block=True
)
Lock the memory clock to a specified range. Units: MHz.
Source code in zeus/device/gpu/common.py
63 64 65 66 67 68 |
|
resetMemoryLockedClocks
abstractmethod
resetMemoryLockedClocks(_block=True)
Reset the locked memory clocks to the default.
Source code in zeus/device/gpu/common.py
70 71 72 73 |
|
getSupportedGraphicsClocks
abstractmethod
getSupportedGraphicsClocks(memory_clock_mhz=None)
Return a list of supported graphics clock frequencies. Units: MHz.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
memory_clock_mhz |
int | None
|
Memory clock frequency to use. Some GPUs have different supported graphics clocks depending on the memory clock. |
None
|
Source code in zeus/device/gpu/common.py
75 76 77 78 79 80 81 82 83 84 85 |
|
setGpuLockedClocks
abstractmethod
setGpuLockedClocks(
min_clock_mhz, max_clock_mhz, _block=True
)
Lock the GPU clock to a specified range. Units: MHz.
Source code in zeus/device/gpu/common.py
87 88 89 90 91 92 |
|
resetGpuLockedClocks
abstractmethod
resetGpuLockedClocks(_block=True)
Reset the locked GPU clocks to the default.
Source code in zeus/device/gpu/common.py
94 95 96 97 |
|
getAveragePowerUsage
abstractmethod
getAveragePowerUsage()
Return the average power usage of the GPU. Units: mW.
Source code in zeus/device/gpu/common.py
99 100 101 102 |
|
getInstantPowerUsage
abstractmethod
getInstantPowerUsage()
Return the current power draw of the GPU. Units: mW.
Source code in zeus/device/gpu/common.py
104 105 106 107 |
|
getAverageMemoryPowerUsage
abstractmethod
getAverageMemoryPowerUsage()
Return the average power usage of the GPU's memory. Units: mW.
Source code in zeus/device/gpu/common.py
109 110 111 112 |
|
supportsGetTotalEnergyConsumption
abstractmethod
supportsGetTotalEnergyConsumption()
Check if the GPU supports retrieving total energy consumption.
Source code in zeus/device/gpu/common.py
114 115 116 117 |
|
getTotalEnergyConsumption
abstractmethod
getTotalEnergyConsumption()
Return the total energy consumption of the GPU since driver load. Units: mJ.
Source code in zeus/device/gpu/common.py
119 120 121 122 |
|
EmptyGPUs
Bases: GPUs
A concrete class implementing the GPUs abstract base class, but representing an empty collection of GPUs.
This class is used to represent a scenario where no GPUs are available or detected. Any method call attempting to interact with a GPU will raise a ValueError.
Source code in zeus/device/gpu/common.py
277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 |
|
gpus
property
gpus
Return an empty list as no GPUs are being tracked.
__init__
__init__(ensure_homogeneous=False)
Since this class represents an empty collection of GPUs, no actual initialization of GPU objects is performed.
Source code in zeus/device/gpu/common.py
284 285 286 287 288 289 |
|
__del__
__del__()
Clean up any resources if necessary.
As this class represents an empty collection of GPUs, no specific cleanup is required.
Source code in zeus/device/gpu/common.py
291 292 293 294 295 296 |
|
__len__
__len__()
Return 0, indicating no GPUs are being tracked.
Source code in zeus/device/gpu/common.py
303 304 305 |
|
_ensure_homogeneous
_ensure_homogeneous()
Raise a ValueError as no GPUs are being tracked.
Source code in zeus/device/gpu/common.py
307 308 309 |
|
_warn_sys_admin
_warn_sys_admin()
Raise a ValueError as no GPUs are being tracked.
Source code in zeus/device/gpu/common.py
311 312 313 |
|
getName
getName(gpu_index)
Raise a ValueError as no GPUs are available.
Source code in zeus/device/gpu/common.py
315 316 317 |
|
getPowerManagementLimitConstraints
getPowerManagementLimitConstraints(gpu_index)
Raise a ValueError as no GPUs are available.
Source code in zeus/device/gpu/common.py
319 320 321 |
|
setPowerManagementLimit
setPowerManagementLimit(
gpu_index, power_limit_mw, _block=True
)
Raise a ValueError as no GPUs are available.
Source code in zeus/device/gpu/common.py
323 324 325 326 327 |
|
resetPowerManagementLimit
resetPowerManagementLimit(gpu_index, _block=True)
Raise a ValueError as no GPUs are available.
Source code in zeus/device/gpu/common.py
329 330 331 |
|
setPersistenceMode
setPersistenceMode(gpu_index, enabled, _block=True)
Raise a ValueError as no GPUs are available.
Source code in zeus/device/gpu/common.py
333 334 335 336 337 |
|
getSupportedMemoryClocks
getSupportedMemoryClocks(gpu_index)
Raise a ValueError as no GPUs are available.
Source code in zeus/device/gpu/common.py
339 340 341 |
|
setMemoryLockedClocks
setMemoryLockedClocks(
gpu_index, min_clock_mhz, max_clock_mhz, _block=True
)
Raise a ValueError as no GPUs are available.
Source code in zeus/device/gpu/common.py
343 344 345 346 347 348 349 350 351 |
|
resetMemoryLockedClocks
resetMemoryLockedClocks(gpu_index, _block=True)
Raise a ValueError as no GPUs are available.
Source code in zeus/device/gpu/common.py
353 354 355 |
|
getSupportedGraphicsClocks
getSupportedGraphicsClocks(
gpu_index, memory_clock_mhz=None
)
Raise a ValueError as no GPUs are available.
Source code in zeus/device/gpu/common.py
357 358 359 360 361 |
|
setGpuLockedClocks
setGpuLockedClocks(
gpu_index, min_clock_mhz, max_clock_mhz, _block=True
)
Raise a ValueError as no GPUs are available.
Source code in zeus/device/gpu/common.py
363 364 365 366 367 368 369 370 371 |
|
resetGpuLockedClocks
resetGpuLockedClocks(gpu_index, _block=True)
Raise a ValueError as no GPUs are available.
Source code in zeus/device/gpu/common.py
373 374 375 |
|
getInstantPowerUsage
getInstantPowerUsage(gpu_index)
Raise a ValueError as no GPUs are available.
Source code in zeus/device/gpu/common.py
377 378 379 |
|
supportsGetTotalEnergyConsumption
supportsGetTotalEnergyConsumption(gpu_index)
Raise a ValueError as no GPUs are available.
Source code in zeus/device/gpu/common.py
381 382 383 |
|
getTotalEnergyConsumption
getTotalEnergyConsumption(gpu_index)
Raise a ValueError as no GPUs are available.
Source code in zeus/device/gpu/common.py
385 386 387 |
|
ZeusGPUInvalidArgError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps Invalid Argument.
Source code in zeus/device/gpu/common.py
398 399 400 401 402 403 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
401 402 403 |
|
ZeusGPUNotSupportedError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps Not Supported Operation on GPU.
Source code in zeus/device/gpu/common.py
406 407 408 409 410 411 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
409 410 411 |
|
ZeusGPUNoPermissionError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps No Permission to perform GPU operation.
Source code in zeus/device/gpu/common.py
414 415 416 417 418 419 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
417 418 419 |
|
ZeusGPUAlreadyInitializedError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps Already Initialized GPU.
Source code in zeus/device/gpu/common.py
422 423 424 425 426 427 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
425 426 427 |
|
ZeusGPUNotFoundError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps Not Found GPU.
Source code in zeus/device/gpu/common.py
430 431 432 433 434 435 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
433 434 435 |
|
ZeusGPUInsufficientSizeError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps Insufficient Size.
Source code in zeus/device/gpu/common.py
438 439 440 441 442 443 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
441 442 443 |
|
ZeusGPUInsufficientPowerError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps Insufficient Power.
Source code in zeus/device/gpu/common.py
446 447 448 449 450 451 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
449 450 451 |
|
ZeusGPUDriverNotLoadedError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps Driver Error.
Source code in zeus/device/gpu/common.py
454 455 456 457 458 459 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
457 458 459 |
|
ZeusGPUTimeoutError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps Timeout Error.
Source code in zeus/device/gpu/common.py
462 463 464 465 466 467 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
465 466 467 |
|
ZeusGPUIRQError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps IRQ Error.
Source code in zeus/device/gpu/common.py
470 471 472 473 474 475 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
473 474 475 |
|
ZeusGPULibraryNotFoundError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps Library Not Found Error.
Source code in zeus/device/gpu/common.py
478 479 480 481 482 483 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
481 482 483 |
|
ZeusGPUFunctionNotFoundError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps Function Not Found Error.
Source code in zeus/device/gpu/common.py
486 487 488 489 490 491 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
489 490 491 |
|
ZeusGPUCorruptedInfoROMError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps Corrupted Info ROM Error.
Source code in zeus/device/gpu/common.py
494 495 496 497 498 499 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
497 498 499 |
|
ZeusGPULostError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps Lost GPU Error.
Source code in zeus/device/gpu/common.py
502 503 504 505 506 507 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
505 506 507 |
|
ZeusGPUResetRequiredError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps Reset Required Error.
Source code in zeus/device/gpu/common.py
510 511 512 513 514 515 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
513 514 515 |
|
ZeusGPUOperatingSystemError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps Operating System Error.
Source code in zeus/device/gpu/common.py
518 519 520 521 522 523 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
521 522 523 |
|
ZeusGPULibRMVersionMismatchError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps LibRM Version Mismatch Error.
Source code in zeus/device/gpu/common.py
526 527 528 529 530 531 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
529 530 531 |
|
ZeusGPUMemoryError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps Insufficient Memory Error.
Source code in zeus/device/gpu/common.py
534 535 536 537 538 539 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
537 538 539 |
|
ZeusGPUUnknownError
Bases: ZeusBaseGPUError
Zeus GPU exception that wraps Unknown Error.
Source code in zeus/device/gpu/common.py
542 543 544 545 546 547 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
545 546 547 |
|
ZeusGPUHeterogeneousError
Bases: ZeusBaseGPUError
Exception for when GPUs are not homogeneous.
Source code in zeus/device/gpu/common.py
550 551 552 553 554 555 |
|
__init__
__init__(message)
Source code in zeus/device/gpu/common.py
553 554 555 |
|
get_logger
get_logger(name, level=logging.INFO, propagate=False)
Get a logger with the given name with some formatting configs.
Source code in zeus/utils/logging.py
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 |
|
has_sys_admin
cached
has_sys_admin()
Check if the current process has SYS_ADMIN
capabilities.
Source code in zeus/device/common.py
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 |
|
get_gpus
get_gpus(ensure_homogeneous=False)
Initialize and return a singleton object for GPU management.
This function returns a GPU management object that aims to abstract
the underlying GPU vendor and their specific monitoring library
(pynvml for NVIDIA GPUs and amdsmi for AMD GPUs). Management APIs
are mapped to methods on the returned GPUs
object.
GPU availability is checked in the following order:
- NVIDIA GPUs using
pynvml
- AMD GPUs using
amdsmi
- If both are unavailable, a
ZeusGPUInitError
is raised.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
ensure_homogeneous |
bool
|
If True, ensures that all tracked GPUs have the same name. |
False
|
Source code in zeus/device/gpu/__init__.py
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 |
|