Skip to content

common

zeus.device.cpu.common

Error wrappers and classes common to all CPU vendors.

CpuDramMeasurement dataclass

Represents a measurement of CPU and DRAM energy consumption.

Attributes:

Name Type Description
cpu_mj int

The CPU energy consumption in millijoules.
dram_mj Optional[int]

The DRAM energy consumption in millijoules. Defaults to None.
Source code in zeus/device/cpu/common.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
@dataclass
class CpuDramMeasurement:
    """Represents a measurement of CPU and DRAM energy consumption.

    Attributes:
        cpu_mj (int): The CPU energy consumption in millijoules.
        dram_mj (Optional[int]): The DRAM energy consumption in millijoules. Defaults to None.
    """

    cpu_mj: float
    dram_mj: float | None = None

    def __sub__(self, other: CpuDramMeasurement) -> CpuDramMeasurement:
        """Subtracts the values of another CpuDramMeasurement from this one.

        Args:
            other (CpuDramMeasurement): The other CpuDramMeasurement to subtract.

        Returns:
            CpuDramMeasurement: A new CpuDramMeasurement with the result of the subtraction.
        """
        dram_mj = None
        if self.dram_mj is not None and other.dram_mj is not None:
            dram_mj = self.dram_mj - other.dram_mj
        elif self.dram_mj is not None:
            dram_mj = self.dram_mj
        elif other.dram_mj is not None:
            dram_mj = -other.dram_mj
        return CpuDramMeasurement(self.cpu_mj - other.cpu_mj, dram_mj)

    def __truediv__(self, other: int | float) -> CpuDramMeasurement:
        """Divides the values of this CpuDramMeasurement by a float.

        Args:
            other: The float to divide by.

        Returns:
            CpuDramMeasurement: A new CpuDramMeasurement with the result of the division.

        Raises:
            ZeroDivisionError: If division by zero is attempted.
        """
        if isinstance(other, (int, float)):
            if other == 0:
                raise ZeroDivisionError("Division by zero is not allowed")
            dram_mj = None
            if self.dram_mj is not None:
                dram_mj = self.dram_mj / other
            return CpuDramMeasurement(self.cpu_mj / other, dram_mj)
        else:
            return NotImplemented

__sub__ 

__sub__(other)

Subtracts the values of another CpuDramMeasurement from this one.

Parameters:

Name Type Description Default
other CpuDramMeasurement

The other CpuDramMeasurement to subtract.

 required

Returns:

Name Type Description
CpuDramMeasurement CpuDramMeasurement

A new CpuDramMeasurement with the result of the subtraction.
Source code in zeus/device/cpu/common.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def __sub__(self, other: CpuDramMeasurement) -> CpuDramMeasurement:
    """Subtracts the values of another CpuDramMeasurement from this one.

    Args:
        other (CpuDramMeasurement): The other CpuDramMeasurement to subtract.

    Returns:
        CpuDramMeasurement: A new CpuDramMeasurement with the result of the subtraction.
    """
    dram_mj = None
    if self.dram_mj is not None and other.dram_mj is not None:
        dram_mj = self.dram_mj - other.dram_mj
    elif self.dram_mj is not None:
        dram_mj = self.dram_mj
    elif other.dram_mj is not None:
        dram_mj = -other.dram_mj
    return CpuDramMeasurement(self.cpu_mj - other.cpu_mj, dram_mj)

__truediv__ 

__truediv__(other)

Divides the values of this CpuDramMeasurement by a float.

Parameters:

Name Type Description Default
other int | float

The float to divide by.

 required

Returns:

Name Type Description
CpuDramMeasurement CpuDramMeasurement

A new CpuDramMeasurement with the result of the division.

Raises:

Type Description
ZeroDivisionError

If division by zero is attempted.
Source code in zeus/device/cpu/common.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
def __truediv__(self, other: int | float) -> CpuDramMeasurement:
    """Divides the values of this CpuDramMeasurement by a float.

    Args:
        other: The float to divide by.

    Returns:
        CpuDramMeasurement: A new CpuDramMeasurement with the result of the division.

    Raises:
        ZeroDivisionError: If division by zero is attempted.
    """
    if isinstance(other, (int, float)):
        if other == 0:
            raise ZeroDivisionError("Division by zero is not allowed")
        dram_mj = None
        if self.dram_mj is not None:
            dram_mj = self.dram_mj / other
        return CpuDramMeasurement(self.cpu_mj / other, dram_mj)
    else:
        return NotImplemented

ZeusCPUInitError

Bases: ZeusBaseCPUError

Import error or CPU library initialization failures.

Source code in zeus/device/cpu/common.py 
65
66
67
68
69
70
class ZeusCPUInitError(ZeusBaseCPUError):
    """Import error or CPU library initialization failures."""

    def __init__(self, message: str) -> None:
        """Initialize Zeus Exception."""
        super().__init__(message)

__init__ 

__init__(message)
Source code in zeus/device/cpu/common.py 
68
69
70
def __init__(self, message: str) -> None:
    """Initialize Zeus Exception."""
    super().__init__(message)

ZeusCPUNoPermissionError

Bases: ZeusBaseCPUError

Zeus CPU exception class wrapper for No Permission to perform CPU operation.

Source code in zeus/device/cpu/common.py 
73
74
75
76
77
78
class ZeusCPUNoPermissionError(ZeusBaseCPUError):
    """Zeus CPU exception class wrapper for No Permission to perform CPU operation."""

    def __init__(self, message: str) -> None:
        """Initialize Zeus Exception."""
        super().__init__(message)

__init__ 

__init__(message)
Source code in zeus/device/cpu/common.py 
76
77
78
def __init__(self, message: str) -> None:
    """Initialize Zeus Exception."""
    super().__init__(message)

ZeusCPUNotFoundError

Bases: ZeusBaseCPUError

Zeus CPU exception class wrapper for Not Found CPU.

Source code in zeus/device/cpu/common.py 
81
82
83
84
85
86
class ZeusCPUNotFoundError(ZeusBaseCPUError):
    """Zeus CPU exception class wrapper for Not Found CPU."""

    def __init__(self, message: str) -> None:
        """Initialize Zeus Exception."""
        super().__init__(message)

__init__ 

__init__(message)
Source code in zeus/device/cpu/common.py 
84
85
86
def __init__(self, message: str) -> None:
    """Initialize Zeus Exception."""
    super().__init__(message)

CPU

Bases: ABC

Abstract base class for CPU management.

This class defines the interface for interacting with CPUs, subclasses should implement the methods to interact with specific CPU libraries.

Source code in zeus/device/cpu/common.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
class CPU(abc.ABC):
    """Abstract base class for CPU management.

    This class defines the interface for interacting with CPUs, subclasses should implement the methods to interact with specific CPU libraries.
    """

    def __init__(self, cpu_index: int) -> None:
        """Initialize the CPU with a specified index."""
        self.cpu_index = cpu_index

    @abc.abstractmethod
    def getTotalEnergyConsumption(self) -> CpuDramMeasurement:
        """Returns the total energy consumption of the specified powerzone. Units: mJ."""
        pass

    @abc.abstractmethod
    def supportsGetDramEnergyConsumption(self) -> bool:
        """Returns True if the specified CPU powerzone supports retrieving the subpackage energy consumption."""
        pass

__init__ 

__init__(cpu_index)
Source code in zeus/device/cpu/common.py 
95
96
97
def __init__(self, cpu_index: int) -> None:
    """Initialize the CPU with a specified index."""
    self.cpu_index = cpu_index

getTotalEnergyConsumption abstractmethod 

getTotalEnergyConsumption()

Returns the total energy consumption of the specified powerzone. Units: mJ.

Source code in zeus/device/cpu/common.py 
 99
100
101
102
@abc.abstractmethod
def getTotalEnergyConsumption(self) -> CpuDramMeasurement:
    """Returns the total energy consumption of the specified powerzone. Units: mJ."""
    pass

supportsGetDramEnergyConsumption abstractmethod 

supportsGetDramEnergyConsumption()

Returns True if the specified CPU powerzone supports retrieving the subpackage energy consumption.

Source code in zeus/device/cpu/common.py 
104
105
106
107
@abc.abstractmethod
def supportsGetDramEnergyConsumption(self) -> bool:
    """Returns True if the specified CPU powerzone supports retrieving the subpackage energy consumption."""
    pass

CPUs

Bases: ABC

An abstract base class for CPU manager object.

This class defines the essential interface and common functionality for CPU management, instantiating multiple CPU objects for each CPU being tracked. Forwards the call for a specific method to the corresponding CPU object.

Source code in zeus/device/cpu/common.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
class CPUs(abc.ABC):
    """An abstract base class for CPU manager object.

    This class defines the essential interface and common functionality for CPU management, instantiating multiple `CPU` objects for each CPU being tracked.
    Forwards the call for a specific method to the corresponding CPU object.
    """

    @abc.abstractmethod
    def __init__(self) -> None:
        """Initializes the CPU management library to communicate with the CPU driver and sets up tracking for specified CPUs."""
        pass

    @abc.abstractmethod
    def __del__(self) -> None:
        """Shuts down the CPU monitoring library to release resources and clean up."""
        pass

    @property
    @abc.abstractmethod
    def cpus(self) -> Sequence[CPU]:
        """Returns a list of CPU objects being tracked."""
        pass

    def getTotalEnergyConsumption(self, index: int) -> CpuDramMeasurement:
        """Returns the total energy consumption of the specified powerzone. Units: mJ."""
        return self.cpus[index].getTotalEnergyConsumption()

    def supportsGetDramEnergyConsumption(self, index: int) -> bool:
        """Returns True if the specified CPU powerzone supports retrieving the subpackage energy consumption."""
        return self.cpus[index].supportsGetDramEnergyConsumption()

    def __len__(self) -> int:
        """Returns the number of CPUs being tracked."""
        return len(self.cpus)

cpus abstractmethod property 

cpus

Returns a list of CPU objects being tracked.

__init__ abstractmethod 

__init__()
Source code in zeus/device/cpu/common.py 
117
118
119
120
@abc.abstractmethod
def __init__(self) -> None:
    """Initializes the CPU management library to communicate with the CPU driver and sets up tracking for specified CPUs."""
    pass

__del__ abstractmethod 

__del__()

Shuts down the CPU monitoring library to release resources and clean up.

Source code in zeus/device/cpu/common.py 
122
123
124
125
@abc.abstractmethod
def __del__(self) -> None:
    """Shuts down the CPU monitoring library to release resources and clean up."""
    pass

getTotalEnergyConsumption 

getTotalEnergyConsumption(index)

Returns the total energy consumption of the specified powerzone. Units: mJ.

Source code in zeus/device/cpu/common.py 
133
134
135
def getTotalEnergyConsumption(self, index: int) -> CpuDramMeasurement:
    """Returns the total energy consumption of the specified powerzone. Units: mJ."""
    return self.cpus[index].getTotalEnergyConsumption()

supportsGetDramEnergyConsumption 

supportsGetDramEnergyConsumption(index)

Returns True if the specified CPU powerzone supports retrieving the subpackage energy consumption.

Source code in zeus/device/cpu/common.py 
137
138
139
def supportsGetDramEnergyConsumption(self, index: int) -> bool:
    """Returns True if the specified CPU powerzone supports retrieving the subpackage energy consumption."""
    return self.cpus[index].supportsGetDramEnergyConsumption()

__len__ 

__len__()

Returns the number of CPUs being tracked.

Source code in zeus/device/cpu/common.py 
141
142
143
def __len__(self) -> int:
    """Returns the number of CPUs being tracked."""
    return len(self.cpus)

EmptyCPUs

Bases: CPUs

Empty CPUs management object to be used when CPUs management object is unavailable.

Calls to any methods will return a value error and the length of this object will be 0

Source code in zeus/device/cpu/common.py 
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
class EmptyCPUs(CPUs):
    """Empty CPUs management object to be used when CPUs management object is unavailable.

    Calls to any methods will return a value error and the length of this object will be 0
    """

    def __init__(self) -> None:
        """Instantiates empty CPUs object."""
        pass

    def __del__(self) -> None:
        """Shuts down the Intel CPU monitoring."""
        pass

    @property
    def cpus(self) -> Sequence[CPU]:
        """Returns a list of CPU objects being tracked."""
        return []

    def getTotalEnergyConsumption(self, index: int) -> CpuDramMeasurement:
        """Returns the total energy consumption of the specified powerzone. Units: mJ."""
        raise ValueError("No CPUs available.")

    def supportsGetDramEnergyConsumption(self, index: int) -> bool:
        """Returns True if the specified CPU powerzone supports retrieving the subpackage energy consumption."""
        raise ValueError("No CPUs available.")

    def __len__(self) -> int:
        """Returns 0 since the object is empty."""
        return 0

cpus property 

cpus

Returns a list of CPU objects being tracked.

__init__ 

__init__()
Source code in zeus/device/cpu/common.py 
152
153
154
def __init__(self) -> None:
    """Instantiates empty CPUs object."""
    pass

__del__ 

__del__()

Shuts down the Intel CPU monitoring.

Source code in zeus/device/cpu/common.py 
156
157
158
def __del__(self) -> None:
    """Shuts down the Intel CPU monitoring."""
    pass

getTotalEnergyConsumption 

getTotalEnergyConsumption(index)

Returns the total energy consumption of the specified powerzone. Units: mJ.

Source code in zeus/device/cpu/common.py 
165
166
167
def getTotalEnergyConsumption(self, index: int) -> CpuDramMeasurement:
    """Returns the total energy consumption of the specified powerzone. Units: mJ."""
    raise ValueError("No CPUs available.")

supportsGetDramEnergyConsumption 

supportsGetDramEnergyConsumption(index)

Returns True if the specified CPU powerzone supports retrieving the subpackage energy consumption.

Source code in zeus/device/cpu/common.py 
169
170
171
def supportsGetDramEnergyConsumption(self, index: int) -> bool:
    """Returns True if the specified CPU powerzone supports retrieving the subpackage energy consumption."""
    raise ValueError("No CPUs available.")

__len__ 

__len__()

Returns 0 since the object is empty.

Source code in zeus/device/cpu/common.py 
173
174
175
def __len__(self) -> int:
    """Returns 0 since the object is empty."""
    return 0