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 
12
13
14
15
16
17
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 
15
16
17
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 
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
@dataclass
class SoCMeasurement(abc.ABC, metaclass=DeprecatedAliasABCMeta):
    """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

    @deprecated_alias("zeroAllFields")
    @abc.abstractmethod
    def zero_all_fields(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 
35
36
37
38
@abc.abstractmethod
def __sub__(self, other) -> SoCMeasurement:
    """Produce a single measurement object containing differences across all fields."""
    pass

zero_all_fields abstractmethod 

zero_all_fields()

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

Source code in zeus/device/soc/common.py 
40
41
42
43
44
@deprecated_alias("zeroAllFields")
@abc.abstractmethod
def zero_all_fields(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 
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
94
95
96
97
98
99
class SoC(abc.ABC, metaclass=DeprecatedAliasABCMeta):
    """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
        `begin_window` and `end_window`, 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] = {}

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

    @deprecated_alias("getTotalEnergyConsumption")
    @abc.abstractmethod
    def get_total_energy_consumption(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

    @deprecated_alias("beginWindow")
    def begin_window(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.get_total_energy_consumption()

    @deprecated_alias("endWindow")
    def end_window(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.get_total_energy_consumption()
        return end_cumulative - start_cumulative

__init__ 

__init__()

If a derived class implementation intends to rely on this base class's implementation of begin_window and end_window, 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 
53
54
55
56
57
58
59
60
def __init__(self) -> None:
    """Initialize the SoC class.

    If a derived class implementation intends to rely on this base class's implementation of
    `begin_window` and `end_window`, 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] = {}

get_available_metrics abstractmethod 

get_available_metrics()

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

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

get_total_energy_consumption abstractmethod 

get_total_energy_consumption()

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 
68
69
70
71
72
73
74
75
76
77
78
79
@deprecated_alias("getTotalEnergyConsumption")
@abc.abstractmethod
def get_total_energy_consumption(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

begin_window 

begin_window(key)

Begin a measurement interval labeled with key.

Source code in zeus/device/soc/common.py 
81
82
83
84
85
86
87
@deprecated_alias("beginWindow")
def begin_window(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.get_total_energy_consumption()

end_window 

end_window(key)

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

Source code in zeus/device/soc/common.py 
89
90
91
92
93
94
95
96
97
98
99
@deprecated_alias("endWindow")
def end_window(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.get_total_energy_consumption()
    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 
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
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

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

    @deprecated_alias("getTotalEnergyConsumption")
    def get_total_energy_consumption(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.")

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

    @deprecated_alias("endWindow")
    def end_window(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 
105
106
107
def __init__(self) -> None:
    """Initialize an empty SoC class."""
    pass

get_available_metrics 

get_available_metrics()

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

Source code in zeus/device/soc/common.py 
109
110
111
112
@deprecated_alias("getAvailableMetrics")
def get_available_metrics(self) -> set[str]:
    """Return a set of all observable metrics on the current processor."""
    return set()

get_total_energy_consumption 

get_total_energy_consumption()

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 
114
115
116
117
118
119
120
121
122
123
@deprecated_alias("getTotalEnergyConsumption")
def get_total_energy_consumption(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.")

begin_window 

begin_window(key)

Begin a measurement interval labeled with key.

Source code in zeus/device/soc/common.py 
125
126
127
128
@deprecated_alias("beginWindow")
def begin_window(self, key) -> None:
    """Begin a measurement interval labeled with `key`."""
    raise ValueError("No SoC is available.")

end_window 

end_window(key)

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

Source code in zeus/device/soc/common.py 
130
131
132
133
@deprecated_alias("endWindow")
def end_window(self, key) -> SoCMeasurement:
    """End a measurement window and return the energy consumption. Units: mJ."""
    raise ValueError("No SoC is available.")