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

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

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

@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 __str__(self) -> str:
        """Show all fields and their observed values in the measurement object."""
        pass

    @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

__str__ abstractmethod

__str__()

Show all fields and their observed values in the measurement object.

Source code in zeus/device/soc/common.py

@abc.abstractmethod
def __str__(self) -> str:
    """Show all fields and their observed values in the measurement object."""
    pass

__sub__ abstractmethod

__sub__(other)

Produce a single measurement object containing differences across all fields.

Source code in zeus/device/soc/common.py

@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

@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

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 isPresent(self) -> bool:
        """Return if an SoC is present on the current device.

        This should be true for all derived classes of the `SoC` manager except `EmptySoC`.
        """
        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

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

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

isPresent abstractmethod

isPresent()

Return if an SoC is present on the current device.

This should be true for all derived classes of the SoC manager except EmptySoC.

Source code in zeus/device/soc/common.py

@abc.abstractmethod
def isPresent(self) -> bool:
    """Return if an SoC is present on the current device.

    This should be true for all derived classes of the `SoC` manager except `EmptySoC`.
    """
    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

@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

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

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

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 isPresent(self) -> bool:
        """Return if an SoC is present on the current device.

        This should be true for all derived classes of the SoC manager except `EmptySoC`.
        """
        return False

    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

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

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

isPresent

isPresent()

Return if an SoC is present on the current device.

This should be true for all derived classes of the SoC manager except EmptySoC.

Source code in zeus/device/soc/common.py

def isPresent(self) -> bool:
    """Return if an SoC is present on the current device.

    This should be true for all derived classes of the SoC manager except `EmptySoC`.
    """
    return False

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

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

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

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