diff options
Diffstat (limited to 'resources/libraries/python/MLRsearch/discrete_load.py')
| -rw-r--r-- | resources/libraries/python/MLRsearch/discrete_load.py | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/resources/libraries/python/MLRsearch/discrete_load.py b/resources/libraries/python/MLRsearch/discrete_load.py new file mode 100644 index 0000000000..a75b4acf96 --- /dev/null +++ b/resources/libraries/python/MLRsearch/discrete_load.py @@ -0,0 +1,316 @@ +# Copyright (c) 2023 Cisco and/or its affiliates. +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Module defining DiscreteLoad class.""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from functools import total_ordering +from typing import Callable, Optional, Union + +from .load_rounding import LoadRounding +from .discrete_width import DiscreteWidth + + +@total_ordering +@dataclass +class DiscreteLoad: + """Structure to store load value together with its rounded integer form. + + LoadRounding instance is needed to enable conversion between two forms. + Conversion methods and factories are added for convenience. + + In general, the float form is allowed to differ from conversion from int. + + Comparisons are supported, acting on the float load component. + Additive operations are supported, acting on int form. + Multiplication by a float constant is supported, acting on float form. + + As for all user defined classes by default, all instances are truthy. + That is useful when dealing with Optional values, as None is falsy. + + This dataclass is effectively frozen, but cannot be marked as such + as that would prevent LoadStats from being its subclass. + """ + + # For most debugs, rounding in repr just takes space. + rounding: LoadRounding = field(repr=False, compare=False) + """Rounding instance to use for conversion.""" + float_load: float = None + """Float form of intended load [tps], usable for measurer.""" + int_load: int = field(compare=False, default=None) + """Integer form, usable for exact computations.""" + + def __post_init__(self) -> None: + """Ensure types, compute missing information. + + At this point, it is allowed for float load to differ from + conversion from int load. MLRsearch should round explicitly later, + based on its additional information. + + :raises RuntimeError: If both init arguments are None. + """ + if self.float_load is None and self.int_load is None: + raise RuntimeError("Float or int value is needed.") + if self.float_load is None: + self.int_load = int(self.int_load) + self.float_load = self.rounding.int2float(self.int_load) + else: + self.float_load = float(self.float_load) + self.int_load = self.rounding.float2int(self.float_load) + + def __str__(self) -> str: + """Convert to a short human-readable string. + + :returns: The short string. + :rtype: str + """ + return f"int_load={int(self)}" + + # Explicit comparison operators. + # Those generated with dataclass order=True do not allow subclass instances. + + def __eq__(self, other: Optional[DiscreteLoad]) -> bool: + """Return whether the other instance has the same float form. + + None is effectively considered to be an unequal instance. + + :param other: Other instance to compare to, or None. + :type other: Optional[DiscreteLoad] + :returns: True only if float forms are exactly equal. + :rtype: bool + """ + if other is None: + return False + return float(self) == float(other) + + def __lt__(self, other: DiscreteLoad) -> bool: + """Return whether self has smaller float form than the other instance. + + None is not supported, as MLRsearch does not need that + (so when None appears we want to raise). + + :param other: Other instance to compare to. + :type other: DiscreteLoad + :returns: True only if float forms of self is strictly smaller. + :rtype: bool + """ + return float(self) < float(other) + + def __hash__(self) -> int: + """Return a hash based on the float value. + + With this, the instance can be used as if it was immutable and hashable, + e.g. it can be a key in a dict. + + :returns: Hash value for this instance. + :rtype: int + """ + return hash(float(self)) + + @property + def is_round(self) -> bool: + """Return whether float load matches converted int load. + + :returns: False if float load is not rounded. + :rtype: bool + """ + expected = self.rounding.int2float(self.int_load) + return expected == self.float_load + + def __int__(self) -> int: + """Return the int value. + + :returns: The int field value. + :rtype: int + """ + return self.int_load + + def __float__(self) -> float: + """Return the float value. + + :returns: The float field value [tps]. + :rtype: float + """ + return self.float_load + + @staticmethod + def int_conver(rounding: LoadRounding) -> Callable[[int], DiscreteLoad]: + """Return a factory that turns an int load into a discrete load. + + :param rounding: Rounding instance needed. + :type rounding: LoadRounding + :returns: Factory to use when converting from int. + :rtype: Callable[[int], DiscreteLoad] + """ + + def factory_int(int_load: int) -> DiscreteLoad: + """Use rounding and int load to create discrete load. + + :param int_load: Intended load in integer form. + :type int_load: int + :returns: New discrete load instance matching the int load. + :rtype: DiscreteLoad + """ + return DiscreteLoad(rounding=rounding, int_load=int_load) + + return factory_int + + @staticmethod + def float_conver(rounding: LoadRounding) -> Callable[[float], DiscreteLoad]: + """Return a factory that turns a float load into a discrete load. + + :param rounding: Rounding instance needed. + :type rounding: LoadRounding + :returns: Factory to use when converting from float. + :rtype: Callable[[float], DiscreteLoad] + """ + + def factory_float(float_load: float) -> DiscreteLoad: + """Use rounding instance and float load to create discrete load. + + The float form is not rounded yet. + + :param int_load: Intended load in float form [tps]. + :type int_load: float + :returns: New discrete load instance matching the float load. + :rtype: DiscreteLoad + """ + return DiscreteLoad(rounding=rounding, float_load=float_load) + + return factory_float + + def rounded_down(self) -> DiscreteLoad: + """Create and return new instance with float form matching int. + + :returns: New instance with same int form and float form rounded down. + :rtype: DiscreteLoad + """ + return DiscreteLoad(rounding=self.rounding, int_load=int(self)) + + def hashable(self) -> DiscreteLoad: + """Return new equivalent instance. + + This is mainly useful for conversion from unhashable subclasses, + such as LoadStats. + Rounding instance (reference) is copied from self. + + :returns: New instance with values based on float form of self. + :rtype: DiscreteLoad + """ + return DiscreteLoad(rounding=self.rounding, float_load=float(self)) + + def __add__(self, width: DiscreteWidth) -> DiscreteLoad: + """Return newly constructed instance with width added to int load. + + Rounding instance (reference) is copied from self. + + Argument type is checked, to avoid caller adding two loads by mistake + (or adding int to load and similar). + + :param width: Value to add to int load. + :type width: DiscreteWidth + :returns: New instance. + :rtype: DiscreteLoad + :raises RuntimeError: When argument has unexpected type. + """ + if not isinstance(width, DiscreteWidth): + raise RuntimeError(f"Not width: {width!r}") + return DiscreteLoad( + rounding=self.rounding, + int_load=self.int_load + int(width), + ) + + def __sub__( + self, other: Union[DiscreteWidth, DiscreteLoad] + ) -> Union[DiscreteLoad, DiscreteWidth]: + """Return result based on the argument type. + + Load minus load is width, load minus width is load. + This allows the same operator to support both operations. + + Rounding instance (reference) is copied from self. + + :param other: Value to subtract from int load. + :type other: Union[DiscreteWidth, DiscreteLoad] + :returns: Resulting width or load. + :rtype: Union[DiscreteLoad, DiscreteWidth] + :raises RuntimeError: If the argument type is not supported. + """ + if isinstance(other, DiscreteWidth): + return self._minus_width(other) + if isinstance(other, DiscreteLoad): + return self._minus_load(other) + raise RuntimeError(f"Unsupported type {other!r}") + + def _minus_width(self, width: DiscreteWidth) -> DiscreteLoad: + """Return newly constructed instance, width subtracted from int load. + + Rounding instance (reference) is copied from self. + + :param width: Value to subtract from int load. + :type width: DiscreteWidth + :returns: New instance. + :rtype: DiscreteLoad + """ + return DiscreteLoad( + rounding=self.rounding, + int_load=self.int_load - int(width), + ) + + def _minus_load(self, other: DiscreteLoad) -> DiscreteWidth: + """Return newly constructed width instance, difference of int loads. + + Rounding instance (reference) is copied from self. + + :param other: Value to subtract from int load. + :type other: DiscreteLoad + :returns: New instance. + :rtype: DiscreteWidth + """ + return DiscreteWidth( + rounding=self.rounding, + int_width=self.int_load - int(other), + ) + + def __mul__(self, coefficient: float) -> DiscreteLoad: + """Return newly constructed instance, float load multiplied by argument. + + Rounding instance (reference) is copied from self. + + :param coefficient: Value to multiply float load with. + :type coefficient: float + :returns: New instance. + :rtype: DiscreteLoad + :raises RuntimeError: If argument is unsupported. + """ + if not isinstance(coefficient, float): + raise RuntimeError(f"Not float: {coefficient!r}") + if coefficient <= 0.0: + raise RuntimeError(f"Not positive: {coefficient!r}") + return DiscreteLoad( + rounding=self.rounding, + float_load=self.float_load * coefficient, + ) + + def __truediv__(self, coefficient: float) -> DiscreteLoad: + """Call multiplication with inverse argument. + + :param coefficient: Value to divide float load with. + :type coefficient: float + :returns: New instance. + :rtype: DiscreteLoad + :raises RuntimeError: If argument is unsupported. + """ + return self * (1.0 / coefficient) |