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
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.
    """

    @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")
    @abc.abstractmethod
    def begin_window(self, key: str, restart: bool = False) -> None:
        """Begin a measurement interval labeled with `key`.

        Args:
            key: Unique name of the measurement window.
            restart: If True and the window already exists, cancel the existing
                window and start a new one.
        """
        pass

    @deprecated_alias("endWindow")
    @abc.abstractmethod
    def end_window(self, key: str) -> SoCMeasurement:
        """End a measurement window and return the energy consumption. Units: mJ."""
        pass

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 
53
54
55
56
57
@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 
59
60
61
62
63
64
65
66
67
68
69
70
@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 abstractmethod 

begin_window(key, restart=False)

Begin a measurement interval labeled with key.

Parameters:

Name Type Description Default
key str

Unique name of the measurement window.

 required
restart bool

If True and the window already exists, cancel the existing window and start a new one.

 False
Source code in zeus/device/soc/common.py 
72
73
74
75
76
77
78
79
80
81
82
@deprecated_alias("beginWindow")
@abc.abstractmethod
def begin_window(self, key: str, restart: bool = False) -> None:
    """Begin a measurement interval labeled with `key`.

    Args:
        key: Unique name of the measurement window.
        restart: If True and the window already exists, cancel the existing
            window and start a new one.
    """
    pass

end_window abstractmethod 

end_window(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
@deprecated_alias("endWindow")
@abc.abstractmethod
def end_window(self, key: str) -> SoCMeasurement:
    """End a measurement window and return the energy consumption. Units: mJ."""
    pass

EmptySoC

Bases: SoC

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

Source code in zeus/device/soc/common.py 
 91
 92
 93
 94
 95
 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
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: str, restart: bool = False) -> None:
        """Begin a measurement interval labeled with `key`."""
        raise ValueError("No SoC is available.")

    @deprecated_alias("endWindow")
    def end_window(self, key: str) -> 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 
94
95
96
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 
 98
 99
100
101
@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 
103
104
105
106
107
108
109
110
111
112
@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, restart=False)

Begin a measurement interval labeled with key.

Source code in zeus/device/soc/common.py 
114
115
116
117
@deprecated_alias("beginWindow")
def begin_window(self, key: str, restart: bool = False) -> 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 
119
120
121
122
@deprecated_alias("endWindow")
def end_window(self, key: str) -> SoCMeasurement:
    """End a measurement window and return the energy consumption. Units: mJ."""
    raise ValueError("No SoC is available.")