Skip to content

math

frequenz.core.math ¤

Math tools.

Attributes¤

frequenz.core.math.LessThanComparableOrNoneT module-attribute ¤

LessThanComparableOrNoneT = TypeVar(
    "LessThanComparableOrNoneT",
    bound=LessThanComparable | None,
)

Type variable for a value that a LessThanComparable or None.

Classes¤

frequenz.core.math.Interval dataclass ¤

Bases: Generic[LessThanComparableOrNoneT]

An interval to test if a value is within its limits.

The start and end are inclusive, meaning that the start and end limites are included in the range when checking if a value is contained by the interval.

If the start or end is None, it means that the interval is unbounded in that direction.

If start is bigger than end, a ValueError is raised.

The type stored in the interval must be comparable, meaning that it must implement the __lt__ method to be able to compare values.

Source code in frequenz/core/math.py 
 43
 44
 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
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
@dataclass(frozen=True, repr=False)
class Interval(Generic[LessThanComparableOrNoneT]):
    """An interval to test if a value is within its limits.

    The `start` and `end` are inclusive, meaning that the `start` and `end` limites are
    included in the range when checking if a value is contained by the interval.

    If the `start` or `end` is `None`, it means that the interval is unbounded in that
    direction.

    If `start` is bigger than `end`, a `ValueError` is raised.

    The type stored in the interval must be comparable, meaning that it must implement
    the `__lt__` method to be able to compare values.
    """

    start: LessThanComparableOrNoneT
    """The start of the interval."""

    end: LessThanComparableOrNoneT
    """The end of the interval."""

    def __post_init__(self) -> None:
        """Check if the start is less than or equal to the end."""
        if self.start is None or self.end is None:
            return
        start = cast(LessThanComparable, self.start)
        end = cast(LessThanComparable, self.end)
        if start > end:
            raise ValueError(
                f"The start ({self.start}) can't be bigger than end ({self.end})"
            )

    def __contains__(self, item: LessThanComparableOrNoneT) -> bool:
        """
        Check if the value is within the range of the container.

        Args:
            item: The value to check.

        Returns:
            bool: True if value is within the range, otherwise False.
        """
        if item is None:
            return False
        casted_item = cast(LessThanComparable, item)

        if self.start is None and self.end is None:
            return True
        if self.start is None:
            start = cast(LessThanComparable, self.end)
            return not casted_item > start
        if self.end is None:
            return not self.start > item
        # mypy seems to get confused here, not being able to narrow start and end to
        # just LessThanComparable, complaining with:
        #   error: Unsupported left operand type for <= (some union)
        # But we know if they are not None, they should be LessThanComparable, and
        # actually mypy is being able to figure it out in the lines above, just not in
        # this one, so it should be safe to cast.
        return not (
            casted_item < cast(LessThanComparable, self.start)
            or casted_item > cast(LessThanComparable, self.end)
        )

    def __repr__(self) -> str:
        """Return a string representation of this instance."""
        return f"Interval({self.start!r}, {self.end!r})"

    def __str__(self) -> str:
        """Return a string representation of this instance."""
        start = "∞" if self.start is None else str(self.start)
        end = "∞" if self.end is None else str(self.end)
        return f"[{start}, {end}]"
Attributes¤
end instance-attribute ¤
end: LessThanComparableOrNoneT

The end of the interval.

start instance-attribute ¤
start: LessThanComparableOrNoneT

The start of the interval.

Functions¤
__contains__ ¤
__contains__(item: LessThanComparableOrNoneT) -> bool

Check if the value is within the range of the container.

PARAMETER DESCRIPTION
item

The value to check.

TYPE: LessThanComparableOrNoneT

RETURNS DESCRIPTION
bool

True if value is within the range, otherwise False.

TYPE: bool

Source code in frequenz/core/math.py 
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __contains__(self, item: LessThanComparableOrNoneT) -> bool:
    """
    Check if the value is within the range of the container.

    Args:
        item: The value to check.

    Returns:
        bool: True if value is within the range, otherwise False.
    """
    if item is None:
        return False
    casted_item = cast(LessThanComparable, item)

    if self.start is None and self.end is None:
        return True
    if self.start is None:
        start = cast(LessThanComparable, self.end)
        return not casted_item > start
    if self.end is None:
        return not self.start > item
    # mypy seems to get confused here, not being able to narrow start and end to
    # just LessThanComparable, complaining with:
    #   error: Unsupported left operand type for <= (some union)
    # But we know if they are not None, they should be LessThanComparable, and
    # actually mypy is being able to figure it out in the lines above, just not in
    # this one, so it should be safe to cast.
    return not (
        casted_item < cast(LessThanComparable, self.start)
        or casted_item > cast(LessThanComparable, self.end)
    )
__post_init__ ¤
__post_init__() -> None

Check if the start is less than or equal to the end.

Source code in frequenz/core/math.py 
65
66
67
68
69
70
71
72
73
74
def __post_init__(self) -> None:
    """Check if the start is less than or equal to the end."""
    if self.start is None or self.end is None:
        return
    start = cast(LessThanComparable, self.start)
    end = cast(LessThanComparable, self.end)
    if start > end:
        raise ValueError(
            f"The start ({self.start}) can't be bigger than end ({self.end})"
        )
__repr__ ¤
__repr__() -> str

Return a string representation of this instance.

Source code in frequenz/core/math.py 
108
109
110
def __repr__(self) -> str:
    """Return a string representation of this instance."""
    return f"Interval({self.start!r}, {self.end!r})"
__str__ ¤
__str__() -> str

Return a string representation of this instance.

Source code in frequenz/core/math.py 
112
113
114
115
116
def __str__(self) -> str:
    """Return a string representation of this instance."""
    start = "∞" if self.start is None else str(self.start)
    end = "∞" if self.end is None else str(self.end)
    return f"[{start}, {end}]"

frequenz.core.math.LessThanComparable ¤

Bases: Protocol

A protocol that requires the __lt__ method to compare values.

Source code in frequenz/core/math.py 
30
31
32
33
34
class LessThanComparable(Protocol):
    """A protocol that requires the `__lt__` method to compare values."""

    def __lt__(self, other: Self, /) -> bool:
        """Return whether self is less than other."""
Functions¤
__lt__ ¤
__lt__(other: Self) -> bool

Return whether self is less than other.

Source code in frequenz/core/math.py 
33
34
def __lt__(self, other: Self, /) -> bool:
    """Return whether self is less than other."""

Functions¤

frequenz.core.math.is_close_to_zero ¤

is_close_to_zero(
    value: float, abs_tol: float = 1e-09
) -> bool

Check if a floating point value is close to zero.

A value of 1e-9 is a commonly used absolute tolerance to balance precision and robustness for floating-point numbers comparisons close to zero. Note that this is also the default value for the relative tolerance. For more technical details, see https://peps.python.org/pep-0485/#behavior-near-zero

PARAMETER DESCRIPTION
value

The floating point value to compare to.

TYPE: float

abs_tol

The minimum absolute tolerance. Defaults to 1e-9.

TYPE: float DEFAULT: 1e-09

RETURNS DESCRIPTION
bool

Whether the floating point value is close to zero.
Source code in frequenz/core/math.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
def is_close_to_zero(value: float, abs_tol: float = 1e-9) -> bool:
    """Check if a floating point value is close to zero.

    A value of 1e-9 is a commonly used absolute tolerance to balance precision
    and robustness for floating-point numbers comparisons close to zero. Note
    that this is also the default value for the relative tolerance.
    For more technical details, see https://peps.python.org/pep-0485/#behavior-near-zero

    Args:
        value: The floating point value to compare to.
        abs_tol: The minimum absolute tolerance. Defaults to 1e-9.

    Returns:
        Whether the floating point value is close to zero.
    """
    zero: float = 0.0
    return math.isclose(a=value, b=zero, abs_tol=abs_tol)