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 datadomains (
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 datadomains (
Optional
[List
[Domain
]]) – list of the monitored energy domainsstart_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 devicesdefault_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
- 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