resources/libraries/python/MLRsearch/goal_result.py

   1 # Copyright (c) 2023 Cisco and/or its affiliates.
   2 # Licensed under the Apache License, Version 2.0 (the "License");
   3 # you may not use this file except in compliance with the License.
   4 # You may obtain a copy of the License at:
   5 #
   6 #     http://www.apache.org/licenses/LICENSE-2.0
   7 #
   8 # Unless required by applicable law or agreed to in writing, software
   9 # distributed under the License is distributed on an "AS IS" BASIS,
  10 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  11 # See the License for the specific language governing permissions and
  12 # limitations under the License.
  13
  14 """Module defining GoalResult class."""
  15
  16 from __future__ import annotations
  17
  18 from dataclasses import dataclass
  19 from typing import Optional
  20
  21 from .discrete_load import DiscreteLoad
  22 from .relevant_bounds import RelevantBounds
  23 from .trimmed_stat import TrimmedStat
  24
  25
  26 @dataclass
  27 class GoalResult:
  28     """Composite to be mapped for each search goal at the end of the search.
  29
  30     The values are stored as trimmed stats,
  31     the conditional throughput is returned as a discrete loads.
  32     Thus, users interested only in float values have to convert explicitly.
  33
  34     Irregular goal results are supported as instances with a bound missing.
  35     """
  36
  37     relevant_lower_bound: Optional[TrimmedStat]
  38     """The relevant lower bound for the search goal."""
  39     relevant_upper_bound: Optional[TrimmedStat]
  40     """The relevant lower upper for the search goal."""
  41
  42     @staticmethod
  43     def from_bounds(bounds: RelevantBounds) -> GoalResult:
  44         """Factory, so that the call site can be shorter.
  45
  46         :param bounds: The relevant bounds as found in measurement database.
  47         :type bounds: RelevantBounds
  48         :returns: Newly created instance based on the bounds.
  49         :rtype: GoalResult
  50         """
  51         return GoalResult(
  52             relevant_lower_bound=bounds.clo,
  53             relevant_upper_bound=bounds.chi,
  54         )
  55
  56     @property
  57     def conditional_throughput(self) -> Optional[DiscreteLoad]:
  58         """Compute conditional throughput from the relevant lower bound.
  59
  60         If the relevant lower bound is missing, None is returned.
  61
  62         The conditional throughput has the same semantics as load,
  63         so if load is unidirectional and user wants bidirectional
  64         throughput, the manager has to compensate.
  65
  66         :return: Conditional throughput at the relevant lower bound.
  67         :rtype: Optional[DiscreteLoad]
  68         """
  69         if not (rlb := self.relevant_lower_bound):
  70             return None
  71         stat = next(iter(rlb.target_to_stat.values()))
  72         return rlb * (1.0 - stat.pessimistic_loss_ratio)