calibrax.profiling.energy

Energy monitoring for GPU (via NVML) and CPU (via Intel RAPL). EnergyMonitor runs as a context manager, sampling power draw at a configurable interval.

Energy monitoring via NVML (GPU) and RAPL (CPU).

Provides EnergyMonitor context manager for tracking power consumption during benchmark execution. Gracefully degrades when hardware interfaces are unavailable.

EnergySample(*, timestamp, gpu_power_watts, cpu_energy_joules, gpu_energy_joules) dataclass

Single energy measurement at a point in time.

Attributes:

Name	Type	Description
timestamp	float	Time of measurement (perf_counter).
gpu_power_watts	float | None	Instantaneous GPU power (None if unavailable).
cpu_energy_joules	float | None	Cumulative CPU energy since monitoring start.
gpu_energy_joules	float | None	Cumulative GPU energy since monitoring start.

EnergySummary(*, total_gpu_energy_joules, total_cpu_energy_joules, total_combined_energy_joules, mean_gpu_power_watts, peak_gpu_power_watts, duration_sec, num_samples) dataclass

Aggregated energy usage over a monitoring period.

Attributes:

Name	Type	Description
total_gpu_energy_joules	float | None	Total GPU energy consumed.
total_cpu_energy_joules	float | None	Total CPU energy consumed.
total_combined_energy_joules	float | None	GPU + CPU combined.
mean_gpu_power_watts	float | None	Average GPU power draw.
peak_gpu_power_watts	float | None	Maximum GPU power draw.
duration_sec	float	Monitoring duration.
num_samples	int	Total samples collected.

EnergyMonitor(sample_interval_sec=0.1)

Background energy monitoring via NVML and RAPL.

Uses daemon thread sampling at configurable interval. Gracefully degrades when NVML or RAPL is unavailable.

Usage:

with EnergyMonitor() as mon:
    # ... run benchmark ...
summary = mon.summary

Initialize EnergyMonitor.

Parameters:

Name	Type	Description	Default
sample_interval_sec	float	Seconds between energy samples.	0.1

samples property

Return a copy of all collected samples.

summary property

Compute aggregated energy summary.

Returns:

Type	Description
EnergySummary	EnergySummary with totals, or None fields when unavailable.

__enter__()

Start background energy sampling thread.

__exit__(*args)

Stop background energy sampling thread.