resources/libraries/python/MLRsearch/global_width.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 GlobalWidth class."""
  15
  16
  17 from __future__ import annotations
  18
  19 from dataclasses import dataclass
  20
  21 from .discrete_load import DiscreteLoad
  22 from .discrete_width import DiscreteWidth
  23
  24
  25 @dataclass
  26 class GlobalWidth:
  27     """Primarily used to synchronize external search steps across selectors.
  28
  29     The full name is global current width, but that is too long for identifiers.
  30
  31     While each selector tracks its "local" (per goal) width using expander,
  32     it is important we do not interleave upper external search for two goals.
  33     That is why all selector instances refer to a singleton instance of this.
  34
  35     In general, this value remains constant when main loop iterates over
  36     selectors and when selector iterates over strategies.
  37     After winner is measured, this width is set to winner width value
  38     and for some strategies that width is expanded when external search says so.
  39
  40     The two methods are not really worth creating a new class,
  41     but the main reason is having a name for type hints
  42     that distinguish this from various other "width" and "current" values.
  43     """
  44
  45     width: DiscreteWidth
  46     """Minimum width to apply at next external search step."""
  47     # TODO: Add a setter, so it is easier to add debug logging.
  48
  49     @staticmethod
  50     def from_loads(load0: DiscreteLoad, load1: DiscreteLoad) -> GlobalWidth:
  51         """Initialize the value based on two loads from initial trials.
  52
  53         :param load0: Lower (or equal) load from the two most recent trials.
  54         :param load1: Higher (or equal) load from the two most recent trials.
  55         :type load0: DiscreteLoad
  56         :type load1: DiscreteLoad
  57         :returns: Newly created instance with computed width.
  58         :rtype: GlobalWidth
  59         """
  60         return GlobalWidth(load1 - load0)
  61
  62     def or_larger(self, width: DiscreteWidth) -> DiscreteWidth:
  63         """Return width from argument or self, whichever is larger.
  64
  65         :param width: A selector (strategy) asks if this width is large enough.
  66         :type width: DiscreteWidth
  67         :returns: Argument or current width.
  68         :rtype: DiscreteWidth
  69         """
  70         return width if width > self.width else self.width