Core modules

Decorator

@pyJoules.energy_meter.measure_energy(func=None, handler=<pyJoules.handler.print_handler.PrintHandler object>, domains=None)

Measure the energy consumption of monitored devices during the execution of the decorated function

Parameters

• handler (EnergyHandler) – handler instance that will receive the power consummation data

• domains (Optional[List[Domain]]) – list of the monitored energy domains

Context

class pyJoules.energy_meter.EnergyContext(handler=<pyJoules.handler.print_handler.PrintHandler object>, domains=None, start_tag='start')

__init__(handler=<pyJoules.handler.print_handler.PrintHandler object>, domains=None, start_tag='start')

Measure the energy consumption of monitored devices during the execution of the contextualized code

Parameters

• handler (EnergyHandler) – handler instance that will receive the power consummation data

• domains (Optional[List[Domain]]) – list of the monitored energy domains

• start_tag (str) – first tag of the trace

Class

class pyJoules.energy_meter.EnergyMeter(devices, default_tag='')

Tool used to record the energy consumption of given devices

__init__(devices, default_tag='')

Parameters

• devices (List[Device]) – list of the monitored devices

• default_tag (str) – tag given if no tag were given to a measure

gen_idle(trace)

generate idle values of an energy trace for each sample, wait for the duraction of a sample and measure the energy consumed during this period

Return type

List[Dict[str, float]]

Returns

the list of idle energy consumption for each sample in the trace

get_trace()

return the last trace measured

Raises

EnergyMeterNotStoppedError – if the energy meter isn’t stopped

Return type

EnergyTrace

record(tag=None)

Add a new state to the Trace

Parameters

tag (Optional[str]) – sample name

Raises

EnergyMeterNotStartedError – if the energy meter isn’t started

resume(tag=None)

resume the energy Trace (if no energy trace was launched, start a new one

Parameters

tag (Optional[str]) – sample name

Raises

EnergyMeterNotStoppedError – if the energy meter isn’t stopped

start(tag=None)

Begin a new energy trace

Parameters

tag (Optional[str]) – sample name

stop()

Set the end of the energy trace

Raises

EnergyMeterNotStartedError – if the energy meter isn’t started

class pyJoules.energy_trace.EnergyTrace(samples)

Trace of all EnergySample collected by a meter

__init__(samples)

Parameters

samples (List[EnergySample]) – samples containing in the trace

append(sample)

append a new sample to the trace

clean_data(guards=[])

Remove sample with negative energy values from the trace Guards can be added to specify rules to remove sample

Parameters

guards (List[Callable[[EnergySample], bool]]) – list of function that is used as rules to remove samples. A guard is a function that take a sample as parameter and return True if it must be keept in the trace, False otherwise

remove_idle(idle)

substract idle energy values from the current trace

Parameters

idle (List[Dict[str, float]]) – list of idle consumption values to substract to current trace idle consumption values must be grouped in a dictionary with their domain as key

Raises

ValueError – if the number of values in the list doesn’t match the number of sample in the trace or if a domain of the trace is not in the idle values

class pyJoules.energy_trace.EnergySample(timestamp, tag, duration, energy)

Variables

• timestamp (float) – begining timestamp

• tag (str) – sample tag

• duration (float) – duration of the sample in seconds

• energy (Dict[str, float]) – dictionary that contains the energy consumed during this sample

class pyJoules.device.device_factory.DeviceFactory

static create_devices(domains=None)

Create and configure the Device instance with the given Domains

Parameters

domains (Optional[Domain]) – a list of Domain instance that as to be monitored (if None, return a list of all monitorable devices)

Return type

List[Device]

Returns

a list of device configured with the given Domains

Raises

• NoSuchDeviceError – if a domain depend on a device that doesn’t exist on the current machine

• NoSuchDomainError – if the given domain is not available on the device

Exception

exception pyJoules.exception.PyJoulesException

PyJoules exceptions parent class

exception pyJoules.exception.NoSuchDomainError(domain_name)

Exception raised when a user ask to monitor a domain that is not available on the given device

domain_name

the domain name that is not available on this device

exception pyJoules.exception.NoSuchDeviceError

Exception raised when a Device that does not exist on the current machine is created

exception pyJoules.energy_meter.NoNextStateException

Exception raised when trying to compute duration or energy from a state which is the last state of an energy trace.

exception pyJoules.energy_meter.StateIsNotFinalError

Exception raised when trying to add a state to a non final state on an energy trace

exception pyJoules.energy_meter.EnergyMeterNotStartedError

Exception raised when trying to stop or record on a non started EnergyMeter instance

exception pyJoules.energy_meter.EnergyMeterNotStoppedError

Exception raised when trying to get energy samples from non stopped EnergyMeter instance

exception pyJoules.energy_meter.SampleNotFoundError

Exception raised when trying to retrieve a sample that does not exist on trace