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 
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
63
64
@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 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
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 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
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 
67
68
69
70
71
72
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 
70
71
72
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 
75
76
77
78
79
80
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 
78
79
80
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 
83
84
85
86
87
88
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 
86
87
88
def __init__(self, message: str) -> None:
    """Initialize Zeus Exception."""
    super().__init__(message)

ZeusCPUNotSupportedError

Bases: ZeusBaseCPUError

Zeus CPU exception class wrapper for Not Supported Operation on CPU.

Source code in zeus/device/cpu/common.py 
91
92
93
94
95
96
class ZeusCPUNotSupportedError(ZeusBaseCPUError):
    """Zeus CPU exception class wrapper for Not Supported Operation on CPU."""

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

__init__ 

__init__(message)
Source code in zeus/device/cpu/common.py 
94
95
96
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 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
class CPU(abc.ABC, metaclass=DeprecatedAliasABCMeta):
    """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

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

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

    @abc.abstractmethod
    def get_power_limits(self) -> CpuDramPowerLimits:
        """Returns the power limits of the CPU package and DRAM zones."""
        pass

__init__ 

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

get_total_energy_consumption abstractmethod 

get_total_energy_consumption()

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

Source code in zeus/device/cpu/common.py 
109
110
111
112
113
@deprecated_alias("getTotalEnergyConsumption")
@abc.abstractmethod
def get_total_energy_consumption(self) -> CpuDramMeasurement:
    """Returns the total energy consumption of the specified powerzone. Units: mJ."""
    pass

supports_get_dram_energy_consumption abstractmethod 

supports_get_dram_energy_consumption()

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

Source code in zeus/device/cpu/common.py 
115
116
117
118
119
@deprecated_alias("supportsGetDramEnergyConsumption")
@abc.abstractmethod
def supports_get_dram_energy_consumption(self) -> bool:
    """Returns True if the specified CPU powerzone supports retrieving the subpackage energy consumption."""
    pass

get_power_limits abstractmethod 

get_power_limits()

Returns the power limits of the CPU package and DRAM zones.

Source code in zeus/device/cpu/common.py 
121
122
123
124
@abc.abstractmethod
def get_power_limits(self) -> CpuDramPowerLimits:
    """Returns the power limits of the CPU package and DRAM zones."""
    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 
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
class CPUs(abc.ABC, metaclass=DeprecatedAliasABCMeta):
    """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

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

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

    def get_power_limits(self, index: int) -> CpuDramPowerLimits:
        """Returns the power limits of the specified CPU's package and DRAM zones."""
        return self.cpus[index].get_power_limits()

    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 
134
135
136
137
@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 
139
140
141
142
@abc.abstractmethod
def __del__(self) -> None:
    """Shuts down the CPU monitoring library to release resources and clean up."""
    pass

get_total_energy_consumption 

get_total_energy_consumption(index)

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

Source code in zeus/device/cpu/common.py 
150
151
152
153
@deprecated_alias("getTotalEnergyConsumption")
def get_total_energy_consumption(self, index: int) -> CpuDramMeasurement:
    """Returns the total energy consumption of the specified powerzone. Units: mJ."""
    return self.cpus[index].get_total_energy_consumption()

supports_get_dram_energy_consumption 

supports_get_dram_energy_consumption(index)

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

Source code in zeus/device/cpu/common.py 
155
156
157
158
@deprecated_alias("supportsGetDramEnergyConsumption")
def supports_get_dram_energy_consumption(self, index: int) -> bool:
    """Returns True if the specified CPU powerzone supports retrieving the subpackage energy consumption."""
    return self.cpus[index].supports_get_dram_energy_consumption()

get_power_limits 

get_power_limits(index)

Returns the power limits of the specified CPU's package and DRAM zones.

Source code in zeus/device/cpu/common.py 
160
161
162
def get_power_limits(self, index: int) -> CpuDramPowerLimits:
    """Returns the power limits of the specified CPU's package and DRAM zones."""
    return self.cpus[index].get_power_limits()

__len__ 

__len__()

Returns the number of CPUs being tracked.

Source code in zeus/device/cpu/common.py 
164
165
166
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 
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
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 []

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

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

    def get_power_limits(self, index: int) -> CpuDramPowerLimits:
        """Returns the power limits of the specified CPU's package and DRAM zones."""
        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 
175
176
177
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 
179
180
181
def __del__(self) -> None:
    """Shuts down the Intel CPU monitoring."""
    pass

get_total_energy_consumption 

get_total_energy_consumption(index)

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

Source code in zeus/device/cpu/common.py 
188
189
190
191
@deprecated_alias("getTotalEnergyConsumption")
def get_total_energy_consumption(self, index: int) -> CpuDramMeasurement:
    """Returns the total energy consumption of the specified powerzone. Units: mJ."""
    raise ValueError("No CPUs available.")

supports_get_dram_energy_consumption 

supports_get_dram_energy_consumption(index)

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

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

get_power_limits 

get_power_limits(index)

Returns the power limits of the specified CPU's package and DRAM zones.

Source code in zeus/device/cpu/common.py 
198
199
200
def get_power_limits(self, index: int) -> CpuDramPowerLimits:
    """Returns the power limits of the specified CPU's package and DRAM zones."""
    raise ValueError("No CPUs available.")

__len__ 

__len__()

Returns 0 since the object is empty.

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