measuring-energy

Measuring Energy and Power with Zeus

Zeus is a Python library for measuring and optimizing the energy consumption of any computation running on GPUs, CPUs, and SoCs. Install it with pip install zeus (Python 3.10 or later), or pip install 'zeus[apple]' to enable energy measurement on Apple silicon. Run python -m zeus.show_env to check which frameworks and devices Zeus detects. Full documentation: https://ml.energy/zeus

Choosing an API

For a quick measurement without writing code, run python -m zeus.monitor energy (prints total energy on Ctrl-C) or python -m zeus.monitor power (prints power draw periodically).

Permissions

GPU energy and power measurement requires no special privileges. CPU and DRAM energy measurement uses RAPL (Intel and most modern AMD CPUs), which requires root due to kernel restrictions. Without root, ZeusMonitor reports cpu_energy=None when cpu_indices is omitted or empty, and raises RuntimeError when a non-empty cpu_indices is passed explicitly. Alternatives are running inside Docker as root with the RAPL sysfs directory mounted, or deploying the Zeus daemon (zeusd) and setting ZEUSD_SOCK_PATH so unprivileged processes relay RAPL reads through it.

ZeusMonitor: energy and time of a code block

from zeus.monitor import ZeusMonitor

def run_workload() -> None: ...

if __name__ == "__main__":
    monitor = ZeusMonitor(gpu_indices=[0, 1])

    monitor.begin_window("workload")
    run_workload()
    result = monitor.end_window("workload")

    print(f"{result.time} s, {result.total_energy} J")
    print(result.gpu_energy)  # {0: ..., 1: ...} in Joules

• gpu_indices=None (default) monitors all GPUs. Indices follow CUDA_VISIBLE_DEVICES (NVIDIA) or HIP_VISIBLE_DEVICES (AMD), so index N is cuda:N in frameworks like PyTorch.
• end_window returns a Measurement with time (seconds), gpu_energy (dict of GPU index to Joules), cpu_energy and dram_energy (dict of RAPL package index to Joules, or None when unavailable), and soc_energy (Apple silicon or Jetson subsystem energies in millijoules, or None). result.total_energy is the sum of GPU energy only.
• Multiple windows can be open at once, and they can nest or overlap. Window names must be unique among open windows; use begin_window(key, restart=True) in notebooks where a crashed cell may have left a window open, and end_window(key, cancel=True) to discard a window.
• begin_window and end_window synchronize asynchronously dispatched GPU computations (torch.cuda.synchronize by default) so the window captures exactly the code inside it. Pass sync_execution_with="jax" or "cupy" to the constructor for those frameworks, or sync_execution=False to begin_window/end_window when the workload uses none of them (otherwise a missing framework raises RuntimeError on machines with GPUs).
• GPU energy counters update roughly every 100 ms, so a very short window can read zero energy. Constructing with approx_instant_energy=True replaces such zero readings with instant power draw times window duration, which is an approximation, not a measurement. Never enable it unprompted: explain this implication to the user and get their approval first, or lengthen the window instead. The flag is also unsupported on AMD GPUs that cannot report instant power; end_window raises ZeusGPUNotSupportedError there.
• log_file="measurement.csv" writes one row per completed window.