powerapi-ng / pyrapl

a library to measure the python energy consumption of python code

PyRAPL

About

pyRAPL is a software toolkit to measure the energy footprint of a host machine along the execution of a piece of Python code.

pyRAPL uses the Intel "Running Average Power Limit" (RAPL) technology that estimates power consumption of a CPU. This technology is available on Intel CPU since the Sandy Bridge generation.

More specifically, pyRAPL can measure the energy consumption of the following CPU domains:

• CPU socket package
• DRAM (for server architectures)
• GPU (for client architectures)

Installation

You can install pyRAPL with pip: pip install pyRAPL

Basic usage

Here are some basic usages of pyRAPL. Please note that the reported energy consumption is not only the energy consumption of the code you are running. This includes the global energy consumption of all the process running on the machine during this period, thus including the operating system and other applications. That is why we recommend to eliminate any extra programs that may alter the energy consumption of the machine hosting experiments and to keep only the code under measurement (i.e., no extra applications, such as graphical interface, background running task...). This will give the closest measure to the real energy consumption of the measured code.

Decorate a function to measure its energy consumption

To measure the energy consumed by the machine during the execution of the function foo() run the following code:

	import pyRAPL

	pyRAPL.setup() 

	@pyRAPL.measure
	def foo():
		# Instructions to be evaluated.

	foo()

This will print in the console the recorded energy consumption of all the CPU domains during the execution of function foo.

Configure the decorator specifying the device to monitor

You can easily configure which device and which socket to monitor using the parameters of the pyRAPL.setup function. For example, the following example only monitors the CPU power consumption on the CPU socket 1. By default, pyRAPL monitors all the available devices of the CPU sockets.

	import pyRAPL

	pyRAPL.setup(devices=[pyRAPL.Device.PKG], socket_ids=[1])

	@pyRAPL.measure
	def foo():
		# Instructions to be evaluated.

	foo()	

You can append the device pyRAPL.Device.DRAM to the devices parameter list to monitor RAM device too.

Running the test multiple times

For short functions, you can configure the number of runs and it will calculate the mean energy consumption of all runs. As an example, if you want to run the evaluation 100 times:

	import pyRAPL

	pyRAPL.setup()
	
	
	@pyRAPL.measure(number=100)
	def foo():
		# Instructions to be evaluated.

	for _ in range(100):
		foo()

Configure the output of the decorator

If you want to handle data with different output than the standard one, you can configure the decorator with an Output instance from the pyRAPL.outputs module.

As an example, if you want to write the recorded energy consumption in a .csv file:

	import pyRAPL

	pyRAPL.setup()
	
	csv_output = pyRAPL.outputs.CSVOutput('result.csv')
	
	@pyRAPL.measure(output=csv_output)
	def foo():
		# Instructions to be evaluated.

	for _ in range(100):
		foo()
		
	csv_output.save()

This will produce a csv file of 100 lines. Each line containing the energy consumption recorded during one execution of the function fun. Other predefined Output classes exist to export data to MongoDB and Panda dataframe. You can also create your own Output class (see the documentation)

Measure the energy consumption of a piece of code

To measure the energy consumed by the machine during the execution of a given piece of code, run the following code :

	import pyRAPL

	pyRAPL.setup()
	meter = pyRAPL.Measurement('bar')
	meter.begin()
	# ...
	# Instructions to be evaluated.
	# ...
	meter.end()

You can also access the result of the measurements by using the property meter.result, which returns a Result object.

You can also use an output to handle this results, for example with the .csv output: meter.export(csv_output)

Measure the energy consumption of a block

pyRAPL allows developers to measure a block of instructions using the keyword with as the example below:

	import pyRAPL
	pyRAPL.setup()
	
	with pyRAPL.Measurement('bar'):
		# ...
		# Instructions to be evaluated.
		# ...

This will report the energy consumption of the block. To process the measurements instead of printing them, you can use any Output class that you pass to the Measurement object:

	import pyRAPL
	pyRAPL.setup()
	
	report = pyRAPL.outputs.DataFrameOutput()

	with pyRAPL.Measurement('bar',output=report):
		# ...
		# Instructions to be evaluated.
		# ...

	report.data.head()

Miscellaneous

About

pyRAPL is an open-source project developed by the Spirals research group (University of Lille and Inria) that is part of the PowerAPI initiative.

The documentation is available here.

Mailing list

You can follow the latest news and asks questions by subscribing to our mailing list.

Contributing

If you would like to contribute code, you can do so via GitHub by forking the repository and sending a pull request.

When submitting code, please make every effort to follow existing coding conventions and style in order to keep the code as readable as possible.

pyrapl's Issues

Windows os error

Is it not supported in windows.getting an error
/sys/devices/system/cpu/present/ no such file or directory error.

iteration

Hi,
Is it pyRAPL available for windows? what can be used for windows?

when the "number" is set >1, is a for loop required to run the function or measureit decorator measures it in iteration of number itself?

change save methode to asynchrone in csv/mongo output

DRAM consumption output

Hi everyone,

I've noticed that the DRAM output is expressed in seconds.
"dram (Optional[List[float]]) – list of the RAM energy consumption -expressed in seconds- (one value for each socket) if None, no RAM energy consumption was recorded."

Can you explain why the energy consumption is not expressed in micro-Joules ?
Otherwise, how can I obtain the equivalence in Joules ?

Thank you,
Best regards.

Add mongodb output class

add instance of the abstract class Output

pyRAPL breaks pytest

Measurements of multiple functions

Hello,

I am having some trouble getting pyRAPL to work the way I want to, and was hoping someone might be able to help. I have searched for tutorials already with no luck, leading me here.

Currently I am using the Measurement.begin() and Measurement.end() method to gather the power consumption of a specific piece of code. This then gets saved to a .csv file so that the data can be analyzed later on.

What I would like to do is use this method throughout my code to measure the power consumption of multiple functions in order to determine what has the highest power cost and so on. Currently, I set up pyRAPL once, create a .csv output using a specific file, create the instance of pyRAPL.Measurement, begin and end the measurement around the code in question, export the results to the .csv, and finally save the .csv to flush the buffers.

I have tried repeating this method with other functions in the code, however I get this error: TypeError: vars() argument must have dict attribute. The error occurs on line 46 of buffered_output.py. Any advice on how to fix this issue?

QuickStart :

Tutorial in RTD and README

revert the measure unit back to uJ

in small portion of codes and with the introduction of number we loose a lot of precision when we convert values from uJ to Joules so revert it back

@pyRAPL.measure in demo code returns error: AttributeError: module 'pyRAPL' has no attribute 'measure'

Hi,

When I try your demo code (from PyPI and this repo):

import pyRAPL

pyRAPL.setup() 

@pyRAPL.measure
def foo():
		# Instructions to be evaluated.

    foo()

I get an attribute error: AttributeError: module 'pyRAPL' has no attribute 'measure'.

Can I please request guidance?

Thank you!
Steph

Portability

Use pyRAPL on multiple architecture :

• support for architecture that have psys device

GPU support

Measurements error

I tried to run a simple following example with pyRAPL but something went wrong when measurement ends :

I'm using Fedora 35,
python 3.9.12

Here the code :

import pyRAPL

pyRAPL.setup()

csv_output = pyRAPL.outputs.CSVOutput('results.csv')

@pyRAPL.measureit(output=csv_output)
def test(N):
    a = 0
    for i in range(N):
        a += 1
    return a

test(1000)

csv_output.save()

TypeError                                 Traceback (most recent call last)
~/test_measurement.ipynb Cellule 6 in <cell line: 14>()
     [11]        a += 1
     [12]    return a
---> [14] test(1000)
     [17] csv_output.save()

File ~/.conda/envs/exp_env/lib/python3.9/site-packages/pyRAPL/measurement.py:123, in measureit.<locals>.decorator_measure_energy.<locals>.wrapper_measure(*args, **kwargs)
    121     val = func(*args, **kwargs)
    122 sensor.end()
--> 123 sensor._results = sensor._results / number
    124 sensor.export()
    125 return val

File ~/.conda/envs/exp_env/lib/python3.9/site-packages/pyRAPL/result.py:53, in Result.__truediv__(self, number)
     51 _duration = self.duration / number
     52 _pkg = [j / number for j in self.pkg]
---> 53 _dram = [j / number for j in self.dram]
     54 return Result(self.label, self.timestamp, _duration, _pkg, _dram)

TypeError: 'NoneType' object is not iterable

API proposal

What about providing an API like this:

import pyRAPL

rapl = pyRAPL.PyRAPL()
record = rapl.record(pyRAPL.PKG|pyRAPL.DRAM)
foo()
bar()
record.stop()
pkg_energy = record.energy(pyRAPL.PKG)
dram_energy = record.energy(pyRAPL.DRAM)

with the supported masks: pyRAPL.PKG, pyRAPL.DRAM, pyRAPL.GPU, pyRAPL.ALL

This can be the basis for being included in a ContextManager and/or code annotation.

FileNotFoundError: [Errno 2] No such file or directory: '/sys/devices/system/cpu/present' i.e. Windows support

I ran the example with a simple loop:

import pyRAPL

pyRAPL.setup() 

@pyRAPL.measureit
def foo():
    a = 0
    for x in range(10000000000):
        a += x
    print(x)

foo()

and it gave the above error. It looks like a Linux directory.
Surprised it doesn't support Windows (or did I miss something?)

Negative energy_uj measurement

Hello everyone,

I took some measurements today during the inference from a Neural Network model from a two-socket server processor. The server has two AMD sockets and during the measurement I get from one socket high negative energy in microjoules. Joule has unit in Coulomb * Volt. Coulomb is the electrical charge, I suppose if something is wrong with the measured energy in microjoules from the sensor, either has something changed the electrical charge or something else happening.

What would be that in your opinion? A negative charge, a software issue or something else?

Btw the cooling system was not working properly, maybe that contributed to noise and inference from the heat.