PyPI/MLRsearch/README.rst

   1 Multiple Loss Ratio Search library
   2 ==================================
   3
   4 Origins
   5 -------
   6
   7 This library was developed as a speedup for traditional binary search
   8 in CSIT_ (Continuous System and Integration Testing) project of fd.io_
   9 (Fast Data), one of LFN_ (Linux Foundation Networking) projects.
  10
  11 In order to make this code available in PyPI_ (Python Package Index),
  12 the setuputils stuff has been added,
  13 but after some discussion, the export directory_
  14 is only a symlink to the original place of tightly coupled CSIT code.
  15
  16 Change log
  17 ----------
  18
  19 1.0.0: Logic improvements, independent selectors, exceed ratio support,
  20 better width rounding, conditional throughput as output.
  21 Implementation relies more on dataclasses, code split into smaller files.
  22 API changed considerably, mainly to avoid long argument lists.
  23
  24 0.4.0: Considarable logic improvements, more than two target ratios supported.
  25 API is not backward compatible with previous versions.
  26
  27 0.3.0: Migrated to Python 3.6, small code quality improvements.
  28
  29 0.2.0: Optional parameter "doublings" has been added.
  30
  31 0.1.1: First officially released version.
  32
  33 Usage
  34 -----
  35
  36 High level description
  37 ______________________
  38
  39 A complete application capable of testing performance using MLRsearch
  40 consists of three layers: Manager, Controller and Measurer.
  41 This library provides an implementation for the Controller only,
  42 including all the classes needed to define API between Controller
  43 and other two components.
  44
  45 Users are supposed to implement the whole Manager layer,
  46 and also implement the Measurer layer.
  47 The Measurer instance is injected as a parameter
  48 when the manager calls the controller instance.
  49
  50 The purpose of Measurer instance is to perform one trial measurement.
  51 Upon invocation of measure() method, the controller only specifies
  52 the intended duration and the intended load for the trial.
  53 The call is done using keyword arguments, so the signature has to be:
  54
  55 ..  code-block:: python3
  56
  57     def measure(self, intended_duration, intended_load):
  58
  59 Usually, the trial measurement process also needs other values,
  60 collectively caller a traffic profile. User (the manager instance)
  61 is responsible for initiating the measurer instance accordingly.
  62 Also, the manager is supposed to set up SUT, traffic generator,
  63 and any other component that can affect the result.
  64
  65 For specific input and output objects see the example below.
  66
  67 Example
  68 _______
  69
  70 This is a minimal example showing every configuration attribute.
  71 The measurer does not interact with any real SUT,
  72 it simulates a SUT that is able to forward exactly one million packets
  73 per second (unidirectional traffic only),
  74 not one packet more (fully deterministic).
  75 In these conditions, the conditional throughput for PDR
  76 happens to be accurate within one packet per second.
  77
  78 This is the screen capture of interactive python interpreter
  79 (wrapped so long lines are readable):
  80
  81 ..  code-block:: python3
  82
  83     >>> import dataclasses
  84     >>> from MLRsearch import (
  85     ...     AbstractMeasurer, Config, MeasurementResult,
  86     ...     MultipleLossRatioSearch, SearchGoal,
  87     ... )
  88     >>>
  89     >>> class Hard1MppsMeasurer(AbstractMeasurer):
  90     ...     def measure(self, intended_duration, intended_load):
  91     ...         sent = int(intended_duration * intended_load)
  92     ...         received = min(sent, int(intended_duration * 1e6))
  93     ...         return MeasurementResult(
  94     ...             intended_duration=intended_duration,
  95     ...             intended_load=intended_load,
  96     ...             offered_count=sent,
  97     ...             forwarding_count=received,
  98     ...         )
  99     ...
 100     >>> def print_dot(_):
 101     ...     print(".", end="")
 102     ...
 103     >>> ndr_goal = SearchGoal(
 104     ...     loss_ratio=0.0,
 105     ...     exceed_ratio=0.005,
 106     ...     relative_width=0.005,
 107     ...     initial_trial_duration=1.0,
 108     ...     final_trial_duration=1.0,
 109     ...     duration_sum=61.0,
 110     ...     preceding_targets=2,
 111     ...     expansion_coefficient=2,
 112     ... )
 113     >>> pdr_goal = dataclasses.replace(ndr_goal, loss_ratio=0.005)
 114     >>> config = Config(
 115     ...     goals=[ndr_goal, pdr_goal],
 116     ...     min_load=1e3,
 117     ...     max_load=1e9,
 118     ...     search_duration_max=1.0,
 119     ...     warmup_duration=None,
 120     ... )
 121     >>> controller = MultipleLossRatioSearch(config=config)
 122     >>> result = controller.search(measurer=Hard1MppsMeasurer(), debug=print_dot)
 123     ....................................................................................
 124     ....................................................................................
 125     ....................................................................................
 126     ....................................................................................
 127     ....................................................................................
 128     ....................................................................................
 129     ...>>> print(result)
 130     {SearchGoal(loss_ratio=0.0, exceed_ratio=0.005, relative_width=0.005, initial_trial_
 131     duration=1.0, final_trial_duration=1.0, duration_sum=61.0, preceding_targets=2, expa
 132     nsion_coefficient=2): fl=997497.6029392382,s=(gl=61.0,bl=0.0,gs=0.0,bs=0.0), SearchG
 133     oal(loss_ratio=0.005, exceed_ratio=0.005, relative_width=0.005, initial_trial_durati
 134     on=1.0, final_trial_duration=1.0, duration_sum=61.0, preceding_targets=2, expansion_
 135     coefficient=2): fl=1002508.6747611101,s=(gl=61.0,bl=0.0,gs=0.0,bs=0.0)}
 136     >>> print(f"NDR conditional throughput: {float(result[ndr_goal].conditional_throughp
 137     ut)}")
 138     NDR conditional throughput: 997497.6029392382
 139     >>> print(f"PDR conditional throughput: {float(result[pdr_goal].conditional_throughp
 140     ut)}")
 141     PDR conditional throughput: 1000000.6730730429
 142
 143 Operation logic
 144 ---------------
 145
 146 The currently published `IETF draft`_ describes the logic of version 0.4,
 147 the logic of version 1.0 will be descibed better in the next draft version (-05).
 148
 149 .. _CSIT: https://wiki.fd.io/view/CSIT
 150 .. _fd.io: https://fd.io/
 151 .. _LFN: https://www.linuxfoundation.org/projects/networking/
 152 .. _PyPI: https://pypi.org/project/MLRsearch/
 153 .. _directory: https://gerrit.fd.io/r/gitweb?p=csit.git;a=tree;f=PyPI/MLRsearch;hb=refs/heads/master
 154 .. _IETF draft: https://tools.ietf.org/html/draft-ietf-bmwg-mlrsearch-04