Skip to content

common

zeus.device.soc.common

Error wrappers and classes common to all SoC devices.

ZeusSoCInitError

Bases: ZeusBaseSoCError

Import error for SoC initialization failures.

Source code in zeus/device/soc/common.py 
11
12
13
14
15
16
class ZeusSoCInitError(ZeusBaseSoCError):
    """Import error for SoC initialization failures."""

    def __init__(self, message: str) -> None:
        """Intialize the exception object."""
        super().__init__(message)

__init__ 

__init__(message)
Source code in zeus/device/soc/common.py 
14
15
16
def __init__(self, message: str) -> None:
    """Intialize the exception object."""
    super().__init__(message)

SoCMeasurement dataclass

Bases: ABC

Represents energy consumption metrics of various subsystems on a SoC processor.

Since subsystems available on a SoC processor are highly variable, the fields of this dataclass are entirely up to each derived class.

Fields available and implemented for a specific SoC processor architecture can be found by referring to the SoCMeasurement derived class corresponding to that particular architecture (e.g., AppleSiliconMeasurement for Apple silicon), or by simply printing an instance of that derived class.

Units: mJ

Source code in zeus/device/soc/common.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
@dataclass
class SoCMeasurement(abc.ABC):
    """Represents energy consumption metrics of various subsystems on a SoC processor.

    Since subsystems available on a SoC processor are highly variable, the fields of
    this dataclass are entirely up to each derived class.

    Fields available and implemented for a specific SoC processor architecture can be
    found by referring to the SoCMeasurement derived class corresponding to that
    particular architecture (e.g., `AppleSiliconMeasurement` for Apple silicon),
    or by simply printing an instance of that derived class.

    Units: mJ
    """

    @abc.abstractmethod
    def __sub__(self, other) -> SoCMeasurement:
        """Produce a single measurement object containing differences across all fields."""
        pass

    @abc.abstractmethod
    def zeroAllFields(self) -> None:
        """Set the value of all fields in the measurement object to zero."""
        pass

__sub__ abstractmethod 

__sub__(other)

Produce a single measurement object containing differences across all fields.

Source code in zeus/device/soc/common.py 
34
35
36
37
@abc.abstractmethod
def __sub__(self, other) -> SoCMeasurement:
    """Produce a single measurement object containing differences across all fields."""
    pass

zeroAllFields abstractmethod 

zeroAllFields()

Set the value of all fields in the measurement object to zero.

Source code in zeus/device/soc/common.py 
39
40
41
42
@abc.abstractmethod
def zeroAllFields(self) -> None:
    """Set the value of all fields in the measurement object to zero."""
    pass

SoC

Bases: ABC

An abstract base class for monitoring the energy consumption of a monolithic SoC processor.

This class will be utilized by ZeusMonitor.

Source code in zeus/device/soc/common.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
class SoC(abc.ABC):
    """An abstract base class for monitoring the energy consumption of a monolithic SoC processor.

    This class will be utilized by ZeusMonitor.
    """

    def __init__(self) -> None:
        """Initialize the SoC class.

        If a derived class implementation intends to rely on this base class's implementation of
        `beginWindow` and `endWindow`, it must invoke this constructor in its own. Otherwise, if
        it will override both of those methods, it can skip invoking this.
        """
        self.measurement_states: dict[str, SoCMeasurement] = {}

    @abc.abstractmethod
    def getAvailableMetrics(self) -> set[str]:
        """Return a set of all observable metrics on the current processor."""
        pass

    @abc.abstractmethod
    def getTotalEnergyConsumption(self) -> SoCMeasurement:
        """Returns the total energy consumption of the SoC.

        The measurement should be cumulative; different calls to this function throughout
        the lifetime of a single `SoC` manager object should count from a fixed arbitrary
        point in time.

        Units: mJ.
        """
        pass

    def beginWindow(self, key) -> None:
        """Begin a measurement interval labeled with `key`."""
        if key in self.measurement_states:
            raise KeyError(f"Measurement window '{key}' already exists")

        self.measurement_states[key] = self.getTotalEnergyConsumption()

    def endWindow(self, key) -> SoCMeasurement:
        """End a measurement window and return the energy consumption. Units: mJ."""
        # Retrieve the measurement taken at the start of the window.
        try:
            start_cumulative: SoCMeasurement = self.measurement_states.pop(key)
        except KeyError:
            raise KeyError(f"Measurement window '{key}' does not exist") from None

        end_cumulative: SoCMeasurement = self.getTotalEnergyConsumption()
        return end_cumulative - start_cumulative

__init__ 

__init__()

If a derived class implementation intends to rely on this base class's implementation of beginWindow and endWindow, it must invoke this constructor in its own. Otherwise, if it will override both of those methods, it can skip invoking this.

Source code in zeus/device/soc/common.py 
51
52
53
54
55
56
57
58
def __init__(self) -> None:
    """Initialize the SoC class.

    If a derived class implementation intends to rely on this base class's implementation of
    `beginWindow` and `endWindow`, it must invoke this constructor in its own. Otherwise, if
    it will override both of those methods, it can skip invoking this.
    """
    self.measurement_states: dict[str, SoCMeasurement] = {}

getAvailableMetrics abstractmethod 

getAvailableMetrics()

Return a set of all observable metrics on the current processor.

Source code in zeus/device/soc/common.py 
60
61
62
63
@abc.abstractmethod
def getAvailableMetrics(self) -> set[str]:
    """Return a set of all observable metrics on the current processor."""
    pass

getTotalEnergyConsumption abstractmethod 

getTotalEnergyConsumption()

Returns the total energy consumption of the SoC.

The measurement should be cumulative; different calls to this function throughout the lifetime of a single SoC manager object should count from a fixed arbitrary point in time.

Units: mJ.

Source code in zeus/device/soc/common.py 
65
66
67
68
69
70
71
72
73
74
75
@abc.abstractmethod
def getTotalEnergyConsumption(self) -> SoCMeasurement:
    """Returns the total energy consumption of the SoC.

    The measurement should be cumulative; different calls to this function throughout
    the lifetime of a single `SoC` manager object should count from a fixed arbitrary
    point in time.

    Units: mJ.
    """
    pass

beginWindow 

beginWindow(key)

Begin a measurement interval labeled with key.

Source code in zeus/device/soc/common.py 
77
78
79
80
81
82
def beginWindow(self, key) -> None:
    """Begin a measurement interval labeled with `key`."""
    if key in self.measurement_states:
        raise KeyError(f"Measurement window '{key}' already exists")

    self.measurement_states[key] = self.getTotalEnergyConsumption()

endWindow 

endWindow(key)

End a measurement window and return the energy consumption. Units: mJ.

Source code in zeus/device/soc/common.py 
84
85
86
87
88
89
90
91
92
93
def endWindow(self, key) -> SoCMeasurement:
    """End a measurement window and return the energy consumption. Units: mJ."""
    # Retrieve the measurement taken at the start of the window.
    try:
        start_cumulative: SoCMeasurement = self.measurement_states.pop(key)
    except KeyError:
        raise KeyError(f"Measurement window '{key}' does not exist") from None

    end_cumulative: SoCMeasurement = self.getTotalEnergyConsumption()
    return end_cumulative - start_cumulative

EmptySoC

Bases: SoC

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

Source code in zeus/device/soc/common.py 
 96
 97
 98
 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
class EmptySoC(SoC):
    """Empty SoC management object to be used when SoC management object is unavailable."""

    def __init__(self) -> None:
        """Initialize an empty SoC class."""
        pass

    def getAvailableMetrics(self) -> set[str]:
        """Return a set of all observable metrics on the current processor."""
        return set()

    def getTotalEnergyConsumption(self) -> SoCMeasurement:
        """Returns the total energy consumption of the SoC.

        The measurement should be cumulative, with different calls to this function all
        counting from a fixed arbitrary point in time.

        Units: mJ.
        """
        raise ValueError("No SoC is available.")

    def beginWindow(self, key) -> None:
        """Begin a measurement interval labeled with `key`."""
        raise ValueError("No SoC is available.")

    def endWindow(self, key) -> SoCMeasurement:
        """End a measurement window and return the energy consumption. Units: mJ."""
        raise ValueError("No SoC is available.")

__init__ 

__init__()
Source code in zeus/device/soc/common.py 
 99
100
101
def __init__(self) -> None:
    """Initialize an empty SoC class."""
    pass

getAvailableMetrics 

getAvailableMetrics()

Return a set of all observable metrics on the current processor.

Source code in zeus/device/soc/common.py 
103
104
105
def getAvailableMetrics(self) -> set[str]:
    """Return a set of all observable metrics on the current processor."""
    return set()

getTotalEnergyConsumption 

getTotalEnergyConsumption()

Returns the total energy consumption of the SoC.

The measurement should be cumulative, with different calls to this function all counting from a fixed arbitrary point in time.

Units: mJ.

Source code in zeus/device/soc/common.py 
107
108
109
110
111
112
113
114
115
def getTotalEnergyConsumption(self) -> SoCMeasurement:
    """Returns the total energy consumption of the SoC.

    The measurement should be cumulative, with different calls to this function all
    counting from a fixed arbitrary point in time.

    Units: mJ.
    """
    raise ValueError("No SoC is available.")

beginWindow 

beginWindow(key)

Begin a measurement interval labeled with key.

Source code in zeus/device/soc/common.py 
117
118
119
def beginWindow(self, key) -> None:
    """Begin a measurement interval labeled with `key`."""
    raise ValueError("No SoC is available.")

endWindow 

endWindow(key)

End a measurement window and return the energy consumption. Units: mJ.

Source code in zeus/device/soc/common.py 
121
122
123
def endWindow(self, key) -> SoCMeasurement:
    """End a measurement window and return the energy consumption. Units: mJ."""
    raise ValueError("No SoC is available.")