Usage Examples

Basic Usage

In this section, we demonstrate how to measure energy consumption with a basic function using CompJouleS.

Measuring Energy Consumption with a Basic Function

To measure the energy consumption of a function, you can use the measure_energy decorator. This decorator allows you to specify the devices to monitor during the execution of your function.

from pyJoules.energy_meter import measure_energy
from pyJoules.device.rapl_device import RaplPackageDomain, RaplCoreDomain
from pyJoules.device.nvidia_device import NvidiaGPUDomain

@measure_energy(domains=[RaplPackageDomain(0), RaplCoreDomain(0), NvidiaGPUDomain(0)])
def example_function():
    # Function implementation
    pass

example_function()

In this example, the measure_energy decorator is applied to example_function, monitoring the energy consumption of the CPU package, CPU core, and NVIDIA GPU.

Logging Energy Consumption

In addition to measuring energy consumption, you can log the data to a CSV file for further analysis.

Using CSVHandler to Log Energy Data

To log energy consumption data, you can use the CSVHandler class. This allows you to save the energy measurements into a CSV file.

from pyJoules.energy_meter import measure_energy
from pyJoules.handler.csv_handler import CSVHandler
from pyJoules.device.rapl_device import RaplPackageDomain
from pyJoules.device.nvidia_device import NvidiaGPUDomain

csv_handler = CSVHandler('energy_log.csv')

@measure_energy(handler=csv_handler, domains=[RaplPackageDomain(0), NvidiaGPUDomain(0)])
def foo():
    # Instructions to be evaluated
    pass

for _ in range(100):
    foo()

csv_handler.save_data()

In this example, the energy consumption of the foo function is measured and logged to the energy_log.csv file after 100 iterations.

Using Context Manager

To add more flexibility to your measurements, such as tagging specific points within your code, you can use the EnergyContext context manager.

Adding Tagged “Breakpoints” in Measurement

Using the EnergyContext allows you to tag different parts of your code to measure energy consumption between specific points.

from pyJoules.energy_meter import EnergyContext
from pyJoules.device.rapl_device import RaplPackageDomain
from pyJoules.device.nvidia_device import NvidiaGPUDomain
from pyJoules.handler.csv_handler import CSVHandler

csv_handler = CSVHandler('result.csv')

with EnergyContext(handler=csv_handler, domains=[RaplPackageDomain(1), NvidiaGPUDomain(0)], start_tag='foo') as ctx:
    # First part of the function
    ctx.record(tag='bar')
    # Second part of the function

csv_handler.save_data()

In this example, the energy consumption is measured from the start of the EnergyContext to the ctx.record call (tagged as ‘foo’) and then from the ctx.record call to the end (tagged as ‘bar’). The results are saved in the result.csv file.