Manual usage

Use a EnergyMeter to measure energy consumption without decorator or context manager

If you want need more flexibility and measure energy consumption of piece of code that can’t be bound inside a decorated function of a context manager, you can use an instance of EnergyMeter .

Instance of EnergyMeter is the underlayer tool used by context manager and decorator to measure energy consumption.

Create the EnergyMeter

Before using an energy meter, you have to create it with devices that it have to monitor. For this, use an DeviceFactory to create and configure the monitored devices

The following piece of code show how to create an EnergyMeter that monitor CPU, DRAM and GPU energy consumption.

domains = [RaplPackageDomain(0), RaplDramDomain(0), NvidiaGPUDomain(0)]
devices = DeviceFactory.create_devices(domains)
meter = EnergyMeter(devices)

Tips : call the DeviceFactory.create_devices without parameter to get the list of all monitorable devices.

Use the EnergyMeter

When you have your EnergyMeter you can use it to measure energy consumption of piece of code.

An EnergyMeter have three main method :

  • start : to start the energy consumption monitoring

  • record : to tag a hotspot in monitored piece of code

  • stop : to stop the energy consumption monitoring

The following piece of code show how to use an EnergyMeter to monitor piece of code:

meter.start(tag='foo')
foo()
meter.record(tag='bar')
bar()
meter.stop()

Get the EnergyTrace

When you finished to measure the energy consumed during execution of your piece of code, you can retrieve its energy trace using the EnergyMeter.get_trace method

This will return an iterator on some EnergySample . Each energy sample contains energy consumption information measured between each call to start , record and stop method.

For example, the trace of the previous example contains two EnergySample . One that contains the energy measured between start and record methods (during foo method execution) and the second that contains energy measured between record and stop method (during bar method execution) .

Energy sample contains :

  • a tag

  • a timestamp (the beginning of the measure)

  • the duration of the measure

  • the energy consumed during the measure

Full Example

from pyJoules.device import DeviceFactory
from pyJoules.device.rapl_device import RaplPackageDomain, RaplDramDomain
from pyJoules.device.nvidia_device import NvidiaGPUDomain
from pyJoules.energy_meter import EnergyMeter

domains = [RaplPackageDomain(0), RaplDramDomain(0), NvidiaGPUDomain(0)]
devices = DeviceFactory.create_devices(domains)
meter = EnergyMeter(devices)

meter.start(tag='foo')
foo()
meter.record(tag='bar')
bar()
meter.stop()

trace = meter.get_trace()